payment-kit 1.16.17 → 1.16.19

package/api/src/libs/invoice.ts

@@ -2,7 +2,7 @@ import { component } from '@blocklet/sdk';
 import type { LiteralUnion } from 'type-fest';
 import { withQuery } from 'ufo';
 
-import { fromUnitToToken } from '@ocap/util';
+import { BN, fromUnitToToken } from '@ocap/util';
 import { Op } from 'sequelize';
 import { cloneDeep, pick } from 'lodash';
 import {
@@ -10,18 +10,32 @@ import {
   Invoice,
   InvoiceItem,
   PaymentCurrency,
+  PaymentIntent,
   PaymentMethod,
+  PaymentSettings,
   Price,
   Product,
   Refund,
   SetupIntent,
+  SimpleCustomField,
   Subscription,
   SubscriptionItem,
+  TInvoice,
+  TLineItemExpanded,
   UsageRecord,
 } from '../store/models';
 import { getConnectQueryParam } from './util';
-import { expandLineItems } from './session';
-import { getSubscriptionCycleAmount, getSubscriptionCycleSetup, getSubscriptionStakeAmountSetup } from './subscription';
+import { expandLineItems, getPriceUintAmountByCurrency } from './session';
+import dayjs from './dayjs';
+import {
+  getSubscriptionCycleAmount,
+  getSubscriptionCycleSetup,
+  getSubscriptionItemPrice,
+  getSubscriptionStakeAmountSetup,
+  isSubscriptionOverdraftProtectionEnabled,
+} from './subscription';
+import logger from './logger';
+import { ensureOverdraftProtectionPrice } from './overdraft-protection';
 
 export function getCustomerInvoicePageUrl({
   invoiceId,
@@ -345,3 +359,571 @@ export async function getStakingInvoices(subscription: Subscription): Promise<In
   );
   return invoices;
 }
+
+type BaseInvoiceProps = {
+  customer: Customer;
+  subscription?: Subscription;
+  currency_id: string;
+  livemode: boolean;
+  period_start: number;
+  period_end: number;
+  status?: string;
+  billing_reason: string;
+  description: string;
+  statement_descriptor?: string;
+  total: string;
+  amount_due?: string;
+  amount_paid?: string;
+  amount_remaining?: string;
+  default_payment_method_id: string;
+  payment_intent_id?: string;
+  checkout_session_id?: string;
+  metadata?: Record<string, any>;
+  items?: Array<{
+    price_id: string;
+    amount: string;
+    quantity: number;
+    description: string;
+    period?: {
+      start: number;
+      end: number;
+    };
+    metadata?: Record<string, any>;
+    subscription_item_id?: string;
+  }>;
+  auto_advance?: boolean;
+  paid?: boolean;
+  paid_out_of_band?: boolean;
+  payment_settings?: PaymentSettings;
+  footer?: string;
+  custom_fields?: SimpleCustomField[];
+  starting_token_balance?: Record<string, string>;
+  ending_token_balance?: Record<string, string>;
+  subtotal_excluding_tax?: string;
+  collection_method?: 'charge_automatically' | 'send_invoice';
+};
+
+async function createInvoiceWithItems(props: BaseInvoiceProps): Promise<{
+  invoice: Invoice;
+  items: InvoiceItem[];
+}> {
+  const {
+    customer,
+    subscription,
+    currency_id: currencyId,
+    livemode,
+    period_start: periodStart,
+    period_end: periodEnd,
+    status = 'open',
+    billing_reason: billingReason,
+    description,
+    statement_descriptor: statementDescriptor = '',
+    total,
+    amount_due: amountDue = total,
+    amount_paid: amountPaid = '0',
+    amount_remaining: amountRemaining = total,
+    default_payment_method_id: paymentMethodId,
+    payment_intent_id: paymentIntentId = '',
+    checkout_session_id: checkoutSessionId = '',
+    items: itemsData,
+    metadata = {},
+    paid = false,
+    auto_advance: autoAdvance = true,
+    paid_out_of_band: paidOutOfBand = false,
+    payment_settings: paymentSettings,
+    ...extraProps
+  } = props;
+
+  // create invoice
+  const invoice = await Invoice.create({
+    amount_shipping: '0',
+    starting_balance: '0',
+    ending_balance: '0',
+    subtotal_excluding_tax: '0',
+    starting_token_balance: {},
+    ending_token_balance: {},
+    attempt_count: 0,
+    attempted: false,
+    tax: '0',
+    discounts: [],
+    total_discount_amounts: [],
+    collection_method: 'charge_automatically',
+    ...extraProps,
+    livemode,
+    number: await customer.getInvoiceNumber(),
+    description,
+    statement_descriptor: statementDescriptor,
+    period_start: periodStart,
+    period_end: periodEnd,
+    auto_advance: autoAdvance,
+    paid,
+    paid_out_of_band: paidOutOfBand,
+    status,
+    billing_reason: billingReason,
+    currency_id: currencyId,
+    customer_id: customer.id,
+    default_payment_method_id: paymentMethodId,
+    payment_intent_id: paymentIntentId,
+    subscription_id: subscription?.id,
+    checkout_session_id: checkoutSessionId,
+    total,
+    subtotal: total,
+    amount_due: amountDue,
+    amount_paid: amountPaid,
+    amount_remaining: amountRemaining,
+
+    customer_address: customer.address,
+    customer_email: customer.email,
+    customer_name: customer.name,
+    customer_phone: customer.phone,
+
+    effective_at: dayjs().unix(),
+    status_transitions: {
+      finalized_at: dayjs().unix(),
+    },
+    payment_settings: paymentSettings || subscription?.payment_settings,
+    metadata,
+  });
+
+  if (!itemsData) {
+    return { invoice, items: [] };
+  }
+  // create invoice items
+  const items = await Promise.all(
+    itemsData.map((item) =>
+      InvoiceItem.create({
+        livemode,
+        amount: item.amount,
+        quantity: item.quantity,
+        description: item.description,
+        period: item.period,
+        currency_id: currencyId,
+        customer_id: customer.id,
+        price_id: item.price_id,
+        invoice_id: invoice.id,
+        subscription_id: subscription?.id,
+        subscription_item_id: item.subscription_item_id,
+        discountable: false,
+        discounts: [],
+        discount_amounts: [],
+        proration: false,
+        proration_details: {},
+        metadata: item.metadata || {},
+      })
+    )
+  );
+
+  return { invoice, items };
+}
+
+export async function ensureInvoiceAndItems({
+  customer,
+  currency,
+  subscription,
+  props,
+  lineItems,
+  trialing,
+  metered,
+  applyCredit = true,
+}: {
+  customer: Customer;
+  currency: PaymentCurrency;
+  subscription?: Subscription;
+  props: TInvoice;
+  lineItems: TLineItemExpanded[];
+  trialing: boolean; // do we have trialing
+  metered: boolean; // is the quantity metered
+  applyCredit?: boolean; // should we apply customer credit?
+}): Promise<{ invoice: Invoice; items: InvoiceItem[] }> {
+  // apply possible balance to invoice
+  let remaining = props.total;
+  let result = { starting: {}, ending: {} };
+  if (applyCredit && props.total > '0') {
+    const balance = customer.getBalanceToApply(currency.id, props.total);
+    result = await customer.decreaseTokenBalance(currency.id, balance);
+    remaining = new BN(props.total).sub(new BN(balance)).toString();
+    logger.info('Invoice will use customer credit', { result, remaining, total: props.total });
+  }
+
+  // get subscription items
+  const subscriptionItems = subscription
+    ? await SubscriptionItem.findAll({ where: { subscription_id: subscription?.id } })
+    : [];
+
+  function getLineSetup(x: TLineItemExpanded) {
+    const price = getSubscriptionItemPrice(x);
+    if (price.type === 'recurring' && trialing) {
+      return {
+        price,
+        amount: '0',
+        // @ts-ignore
+        description: trialing ? `${price.product.name} (trialing)` : price.product.name,
+        period: {
+          start: props.period_start,
+          end: props.period_end,
+        },
+      };
+    }
+
+    return {
+      price,
+      amount:
+        x.custom_amount ||
+        new BN(getPriceUintAmountByCurrency(price, props.currency_id)).mul(new BN(x.quantity)).toString(),
+      description: price.product.name,
+      period: undefined,
+    };
+  }
+  // process line items
+  const processedItems = lineItems.map((x: TLineItemExpanded) => {
+    const setup = getLineSetup(x);
+    const { price } = setup;
+    let { quantity } = x;
+    if (price.type === 'recurring') {
+      if (price.recurring?.usage_type === 'metered' && !metered) {
+        quantity = 0;
+      }
+      if (trialing) {
+        quantity = 0;
+      }
+    }
+
+    return {
+      price_id: price.id,
+      amount: quantity > 0 ? setup.amount : '0',
+      quantity,
+      description: setup.description,
+      period: setup.period,
+      metadata: x.metadata || {},
+      subscription_item_id: subscriptionItems.find((si) => si.price_id === price.id)?.id,
+    };
+  });
+
+  return createInvoiceWithItems({
+    customer,
+    subscription,
+    items: processedItems,
+    livemode: props.livemode,
+    status: props.status || 'open',
+    billing_reason: props.billing_reason,
+    description: props.description || '',
+    statement_descriptor: props.statement_descriptor,
+
+    currency_id: props.currency_id,
+    payment_intent_id: props.payment_intent_id,
+    checkout_session_id: props.checkout_session_id,
+    default_payment_method_id: props.default_payment_method_id,
+
+    period_start: props.period_start,
+    period_end: props.period_end,
+    auto_advance: props.auto_advance,
+
+    total: props.total,
+    amount_remaining: props.amount_remaining || remaining,
+    amount_paid: props.amount_paid,
+    amount_due: props.amount_due || remaining,
+    subtotal_excluding_tax: props.total || '0',
+    starting_token_balance: result.starting,
+    ending_token_balance: result.ending,
+
+    footer: props.footer,
+    custom_fields: props.custom_fields,
+    payment_settings: props.payment_settings || subscription?.payment_settings,
+    metadata: {
+      ...props.metadata,
+      starting_token_balance: result.starting,
+      ending_token_balance: result.ending,
+    },
+  });
+}
+
+export async function cleanupInvoiceAndItems(invoiceId: string) {
+  const invoice = await Invoice.findByPk(invoiceId);
+  if (!invoice) {
+    return;
+  }
+  if (invoice.isImmutable()) {
+    return;
+  }
+
+  const removedItem = await InvoiceItem.destroy({ where: { invoice_id: invoiceId } });
+  const removedInvoice = await Invoice.destroy({ where: { id: invoiceId } });
+  logger.info('cleanup invoice and items', { invoiceId, removedItem, removedInvoice });
+}
+
+export async function ensureRechargeInvoice(
+  invoiceProps: {
+    total: string;
+    description?: string;
+    checkout_session_id?: string;
+    currency_id: string;
+    metadata?: any;
+    payment_settings?: any;
+  },
+  subscription: Subscription,
+  paymentMethod: PaymentMethod,
+  customer: Customer
+) {
+  try {
+    const { invoice } = await createInvoiceWithItems({
+      customer,
+      subscription,
+      currency_id: invoiceProps.currency_id,
+      livemode: subscription.livemode,
+      period_start: dayjs().unix(),
+      period_end: dayjs().unix(),
+      status: 'paid',
+      billing_reason: 'recharge',
+      description: invoiceProps?.description || 'Add funds for subscription',
+      total: invoiceProps.total || '0',
+      amount_due: '0',
+      amount_paid: invoiceProps.total || '0',
+      amount_remaining: '0',
+      default_payment_method_id: paymentMethod.id,
+      checkout_session_id: invoiceProps?.checkout_session_id || '',
+      metadata: invoiceProps.metadata || {},
+      auto_advance: false,
+      paid: true,
+      paid_out_of_band: false,
+      payment_settings: invoiceProps?.payment_settings || subscription?.payment_settings,
+    });
+
+    logger.info('create recharge invoice success', {
+      invoice,
+      subscriptionId: subscription?.id,
+      paymentMethod: paymentMethod.id,
+    });
+  } catch (error) {
+    logger.error('ensureRechargeInvoice: create invoice failed', {
+      error,
+      subscriptionId: subscription?.id,
+      paymentMethod: paymentMethod.id,
+    });
+    throw error;
+  }
+}
+
+export async function ensureOverdraftProtectionInvoiceAndItems({
+  customer,
+  subscription,
+  paymentIntent,
+  props,
+}: {
+  customer: Customer;
+  subscription: Subscription;
+  paymentIntent: PaymentIntent;
+  props: Partial<TInvoice> & { period_start: number; period_end: number };
+}): Promise<{ invoice: Invoice; items: InvoiceItem[] }> {
+  const { price, product } = await ensureOverdraftProtectionPrice(subscription.livemode);
+  const invoicePrice = price.currency_options.find((x: any) => x.currency_id === paymentIntent?.currency_id);
+
+  if (!subscription.overdraft_protection?.enabled) {
+    throw new Error('create overdraft protection invoice skipped due to overdraft protection not enabled');
+  }
+
+  if (!invoicePrice) {
+    throw new Error('overdraft protection invoice price not found');
+  }
+  const currency = await PaymentCurrency.findByPk(invoicePrice.currency_id);
+  if (!currency) {
+    throw new Error('overdraft protection invoice currency not found');
+  }
+  const paymentMethod = await PaymentMethod.findByPk(currency?.payment_method_id);
+  if (!paymentMethod) {
+    throw new Error('overdraft protection invoice payment method not found');
+  }
+
+  if (paymentMethod.type !== 'arcblock') {
+    throw new Error(`Payment method ${paymentMethod.type} not supported for overdraft protection`);
+  }
+
+  const { unused } = await isSubscriptionOverdraftProtectionEnabled(subscription, paymentIntent?.currency_id);
+  if (new BN(unused).lt(new BN(invoicePrice.unit_amount))) {
+    throw new Error('create overdraft protection invoice skipped due to insufficient overdraft protection');
+  }
+
+  const result = await createInvoiceWithItems({
+    customer,
+    subscription,
+    currency_id: invoicePrice.currency_id,
+    livemode: subscription.livemode,
+    period_start: props.period_start || 0,
+    period_end: props.period_end || 0,
+    status: props.status,
+    billing_reason: 'overdraft_protection',
+    description: 'Overdraft protection',
+    collection_method: 'send_invoice',
+    default_payment_method_id: paymentMethod.id,
+    total: invoicePrice.unit_amount || '0',
+    items: [
+      {
+        price_id: price.id,
+        amount: invoicePrice.unit_amount || '0',
+        quantity: 1,
+        description: product?.name || '',
+        period: {
+          start: props.period_start || 0,
+          end: props.period_end || 0,
+        },
+      },
+    ],
+    metadata: {
+      ...(props.metadata || {}),
+      payment_intent_id: paymentIntent.id,
+    },
+  });
+
+  await Price.increment({ quantity_sold: 1 }, { where: { id: price.id } });
+  return result;
+}
+
+export async function ensureStakeInvoice(
+  invoiceProps: {
+    total: string;
+    description?: string;
+    checkout_session_id?: string;
+    currency_id: string;
+    billing_reason?: string;
+    metadata?: any;
+    payment_settings?: any;
+  },
+  subscription: Subscription,
+  paymentMethod: PaymentMethod,
+  customer: Customer
+) {
+  if (paymentMethod.type !== 'arcblock') {
+    return;
+  }
+
+  try {
+    const { invoice } = await createInvoiceWithItems({
+      customer,
+      subscription,
+      currency_id: invoiceProps.currency_id,
+      livemode: subscription.livemode,
+      period_start: dayjs().unix(),
+      period_end: subscription.current_period_end,
+      status: 'paid',
+      billing_reason: invoiceProps?.billing_reason || 'stake',
+      description: invoiceProps?.description || 'Stake for subscription',
+      total: invoiceProps.total || '0',
+      amount_due: '0',
+      amount_paid: invoiceProps.total || '0',
+      amount_remaining: '0',
+      default_payment_method_id: paymentMethod.id,
+      checkout_session_id: invoiceProps?.checkout_session_id || '',
+      metadata: invoiceProps.metadata || {},
+      auto_advance: false,
+      paid: true,
+      paid_out_of_band: false,
+      payment_settings: invoiceProps?.payment_settings || subscription?.payment_settings,
+    });
+
+    logger.info('create staking invoice success', {
+      invoice,
+      subscriptionId: subscription?.id,
+      paymentMethod: paymentMethod.id,
+    });
+  } catch (error) {
+    logger.error('ensureStake: create invoice failed', {
+      error,
+      subscriptionId: subscription?.id,
+      paymentMethod: paymentMethod.id,
+    });
+    throw error;
+  }
+}
+
+// mark overdraft protection invoice as void after payment
+export async function handleOverdraftProtectionInvoiceAfterPayment(invoice: Invoice) {
+  try {
+    if (['stake', 'overdraft_protection', 'stake_overdraft_protection'].includes(invoice.billing_reason)) {
+      return;
+    }
+    const subscription = await Subscription.findByPk(invoice.subscription_id);
+    if (!subscription) {
+      logger.info('handle overdraft protection invoice skipped due to subscription not found', {
+        invoiceId: invoice.id,
+      });
+      return;
+    }
+    if (!subscription.overdraft_protection?.enabled) {
+      logger.info('handle overdraft protection invoice skipped due to overdraft protection not enabled', {
+        subscriptionId: subscription.id,
+      });
+      return;
+    }
+    const paymentMethod = await PaymentMethod.findByPk(invoice.default_payment_method_id);
+    if (!paymentMethod || paymentMethod?.type !== 'arcblock') {
+      logger.info('handle overdraft protection invoice skipped due to payment method not supported', {
+        invoiceId: invoice.id,
+        paymentMethodId: paymentMethod?.id,
+      });
+      return;
+    }
+    const paymentIntent = await PaymentIntent.findByPk(invoice.payment_intent_id);
+    if (!paymentIntent) {
+      logger.info('handle overdraft protection invoice skipped due to payment intent not found', {
+        invoiceId: invoice.id,
+      });
+      return;
+    }
+    if (paymentIntent.status !== 'succeeded') {
+      logger.info('handle overdraft protection invoice skipped due to payment intent not succeeded', {
+        invoiceId: invoice.id,
+      });
+      return;
+    }
+    if (paymentIntent.payment_details?.arcblock?.type !== 'transfer') {
+      logger.info('handle overdraft protection invoice skipped due to payment type not transfer', {
+        invoiceId: invoice.id,
+        paymentIntentId: paymentIntent.id,
+      });
+      return;
+    }
+    const overdraftProtectionInvoice = await Invoice.findOne({
+      where: {
+        subscription_id: subscription.id,
+        billing_reason: 'overdraft_protection',
+        'metadata.invoice_id': invoice.id,
+        status: {
+          [Op.notIn]: ['paid', 'void'],
+        },
+      },
+    });
+    if (!overdraftProtectionInvoice) {
+      logger.info('handle overdraft protection invoice skipped due to overdraft protection invoice not found', {
+        invoiceId: invoice.id,
+      });
+      return;
+    }
+
+    if (overdraftProtectionInvoice.payment_intent_id) {
+      const overdraftProtectionPaymentIntent = await PaymentIntent.findOne({
+        where: {
+          id: overdraftProtectionInvoice.payment_intent_id,
+        },
+      });
+      if (overdraftProtectionPaymentIntent) {
+        await overdraftProtectionPaymentIntent.update({
+          status: 'canceled',
+          canceled_at: dayjs().unix(),
+          cancellation_reason: 'void_invoice',
+        });
+      }
+    }
+
+    await overdraftProtectionInvoice.update({
+      status: 'void',
+      status_transitions: {
+        ...(overdraftProtectionInvoice.status_transitions || {}),
+        voided_at: dayjs().unix(),
+      },
+    });
+  } catch (error) {
+    logger.error('handle overdraft protection invoice failed', {
+      error,
+      invoiceId: invoice.id,
+    });
+  }
+}

package/api/src/libs/notification/template/subscription-succeeded.ts

@@ -4,7 +4,7 @@ import pWaitFor from 'p-wait-for';
 import prettyMsI18n from 'pretty-ms-i18n';
 import isEmpty from 'lodash/isEmpty';
 
-import { getPaymentAmountForCycleSubscription } from '../../payment';
+import { getPaymentAmountForCycleSubscription, getCustomerSubscriptionPageUrl } from '../../subscription';
 import { getUserLocale } from '../../../integrations/blocklet/notification';
 import { translate } from '../../../locales';
 import {
@@ -19,7 +19,6 @@ import {
 } from '../../../store/models';
 import { getCustomerInvoicePageUrl, getOneTimeProductInfo } from '../../invoice';
 import { getMainProductName } from '../../product';
-import { getCustomerSubscriptionPageUrl } from '../../subscription';
 import { formatTime, getPrettyMsI18nLocale } from '../../time';
 import { getExplorerLink, getSubscriptionNotificationCustomActions } from '../../util';
 import type { BaseEmailTemplate, BaseEmailTemplateType } from './base';

package/api/src/libs/notification/template/subscription-trial-will-end.ts

@@ -8,9 +8,9 @@ import { getTokenByAddress } from '../../../integrations/arcblock/stake';
 import { getUserLocale } from '../../../integrations/blocklet/notification';
 import { translate } from '../../../locales';
 import { Customer, PaymentMethod, Subscription, PaymentCurrency } from '../../../store/models';
-import { PaymentDetail, getPaymentAmountForCycleSubscription } from '../../payment';
+import { PaymentDetail } from '../../payment';
 import { getMainProductName } from '../../product';
-import { getCustomerSubscriptionPageUrl } from '../../subscription';
+import { getCustomerSubscriptionPageUrl, getPaymentAmountForCycleSubscription } from '../../subscription';
 import { formatTime, getPrettyMsI18nLocale, getSimplifyDuration } from '../../time';
 import type { BaseEmailTemplate, BaseEmailTemplateType } from './base';
 import dayjs from '../../dayjs';

package/api/src/libs/notification/template/subscription-will-renew.ts

@@ -18,9 +18,13 @@ import {
   SubscriptionItem,
   PaymentCurrency,
 } from '../../../store/models';
-import { getPaymentAmountForCycleSubscription, type PaymentDetail } from '../../payment';
+import type { PaymentDetail } from '../../payment';
 import { getMainProductName } from '../../product';
-import { getCustomerSubscriptionPageUrl, getSubscriptionPaymentAddress } from '../../subscription';
+import {
+  getCustomerSubscriptionPageUrl,
+  getSubscriptionPaymentAddress,
+  getPaymentAmountForCycleSubscription,
+} from '../../subscription';
 import { formatTime, getPrettyMsI18nLocale, getSimplifyDuration } from '../../time';
 import { getCustomerRechargeLink, getSubscriptionNotificationCustomActions } from '../../util';
 import type { BaseEmailTemplate, BaseEmailTemplateType } from './base';