payment-kit 1.16.17 → 1.16.19

package/api/src/routes/connect/overdraft-protection.ts

@@ -0,0 +1,120 @@
+import type { CallbackArgs } from '../../libs/auth';
+import { isSubscriptionOverdraftProtectionEnabled } from '../../libs/subscription';
+import { Lock } from '../../store/models';
+import {
+  ensureSubscriptionForOverdraftProtection,
+  executeOcapTransactions,
+  getAuthPrincipalClaim,
+  getOverdraftProtectionStakeTxClaim,
+} from './shared';
+import { ensureStakeInvoice } from '../../libs/invoice';
+
+export default {
+  action: 'overdraft-protection',
+  authPrincipal: false,
+  claims: {
+    authPrincipal: async ({ extraParams }: CallbackArgs) => {
+      const { paymentMethod } = await ensureSubscriptionForOverdraftProtection(
+        extraParams.subscriptionId,
+        extraParams.amount
+      );
+      return getAuthPrincipalClaim(paymentMethod, 'continue');
+    },
+  },
+  onConnect: async ({ userDid, userPk, extraParams }: CallbackArgs) => {
+    const { subscriptionId } = extraParams;
+    const { subscription, paymentMethod, paymentCurrency, stakeAmount } =
+      await ensureSubscriptionForOverdraftProtection(subscriptionId, extraParams.amount);
+    const { remaining } = await isSubscriptionOverdraftProtectionEnabled(subscription);
+
+    const payerAddress = subscription.overdraft_protection?.payment_details?.arcblock?.payer;
+    if (userDid !== payerAddress && remaining !== '0') {
+      // if previous account has remaining overdraft protection, we don't allow to use new account to pay for it
+      throw new Error(
+        `You are not the payer for this subscription. Expected payer: ${payerAddress}, but found: ${userDid}.`
+      );
+    }
+
+    const claims: { [type: string]: [string, object] } = {};
+
+    if (paymentMethod.type === 'arcblock') {
+      // we always need to stake for the subscription
+      claims.staking = [
+        'prepareTx',
+        await getOverdraftProtectionStakeTxClaim({
+          userDid,
+          userPk,
+          paymentCurrency,
+          paymentMethod,
+          stakeAmount,
+          subscription,
+        }),
+      ];
+
+      return claims;
+    }
+
+    throw new Error(`OverdraftProtection: Payment method ${paymentMethod.type} not supported`);
+  },
+
+  onAuth: async ({ request, userDid, userPk, claims, extraParams }: CallbackArgs) => {
+    const { subscriptionId, amount } = extraParams;
+    const { subscription, paymentCurrency, paymentMethod, customer } = await ensureSubscriptionForOverdraftProtection(
+      subscriptionId,
+      amount
+    );
+
+    const afterTxExecution = async (paymentDetails: any) => {
+      await subscription?.update({
+        overdraft_protection: {
+          payment_details: {
+            ...(subscription.overdraft_protection?.payment_details || {}),
+            [paymentMethod.type]: paymentDetails,
+          },
+          enabled: subscription.overdraft_protection?.enabled || false,
+          payment_method_id: paymentMethod.id,
+        },
+      });
+
+      // release the exhausted lock, so that the notification can be sent again if overdraft protection exhausted
+      await Lock.release(`${subscription.id}-${paymentCurrency.id}-overdraft-protection-exhausted`);
+    };
+
+    if (paymentMethod.type === 'arcblock') {
+      const { stakingAmount, ...paymentDetails } = await executeOcapTransactions(
+        userDid,
+        userPk,
+        claims,
+        paymentMethod,
+        request,
+        subscription?.id,
+        paymentCurrency.contract,
+        `overdraft-protection-${subscription.id}`
+      );
+      await ensureStakeInvoice(
+        {
+          total: stakingAmount,
+          description: 'Stake for subscription overdraft protection',
+          currency_id: paymentCurrency.id,
+          billing_reason: 'stake_overdraft_protection',
+          metadata: {
+            payment_details: {
+              arcblock: {
+                tx_hash: paymentDetails?.staking?.tx_hash,
+                payer: paymentDetails?.payer,
+                address: paymentDetails?.staking?.address,
+              },
+            },
+          },
+        },
+        subscription!,
+        paymentMethod,
+        customer!
+      );
+      await afterTxExecution(paymentDetails);
+      return { hash: paymentDetails.tx_hash };
+    }
+
+    throw new Error(`OverdraftProtection: Payment method ${paymentMethod.type} not supported`);
+  },
+};

package/api/src/routes/connect/recharge.ts

@@ -6,8 +6,9 @@ import { executeEvmTransaction, waitForEvmTxConfirm } from '../../integrations/e
 import type { CallbackArgs } from '../../libs/auth';
 import { getGasPayerExtra } from '../../libs/payment';
 import { getTxMetadata } from '../../libs/util';
-import { ensureRechargeInvoice, ensureSubscriptionRecharge, getAuthPrincipalClaim } from './shared';
+import { ensureSubscriptionRecharge, getAuthPrincipalClaim } from './shared';
 import logger from '../../libs/logger';
+import { ensureRechargeInvoice } from '../../libs/invoice';
 
 export default {
   action: 'recharge',

package/api/src/routes/connect/setup.ts

@@ -11,12 +11,12 @@ import { addSubscriptionJob } from '../../queues/subscription';
 import type { TLineItemExpanded } from '../../store/models';
 import {
   ensureSetupIntent,
-  ensureStakeInvoice,
   executeOcapTransactions,
   getAuthPrincipalClaim,
   getDelegationTxClaim,
   getStakeTxClaim,
 } from './shared';
+import { ensureStakeInvoice } from '../../libs/invoice';
 
 export default {
   action: 'setup',

package/api/src/routes/connect/shared.ts

@@ -11,18 +11,17 @@ import isEmpty from 'lodash/isEmpty';
 import { estimateMaxGasForTx, hasStakedForGas } from '../../integrations/arcblock/stake';
 import { encodeApproveItx } from '../../integrations/ethereum/token';
 import { blocklet, ethWallet, wallet } from '../../libs/auth';
-import dayjs from '../../libs/dayjs';
 import logger from '../../libs/logger';
 import { getGasPayerExtra, getTokenLimitsForDelegation } from '../../libs/payment';
-import { getFastCheckoutAmount, getPriceUintAmountByCurrency, getStatementDescriptor } from '../../libs/session';
+import { getFastCheckoutAmount, getStatementDescriptor } from '../../libs/session';
 import {
   expandSubscriptionItems,
   getSubscriptionCreateSetup,
-  getSubscriptionItemPrice,
   getSubscriptionPaymentAddress,
   getSubscriptionStakeSetup,
 } from '../../libs/subscription';
 import { getCustomerStakeAddress, OCAP_PAYMENT_TX_TYPE } from '../../libs/util';
+
 import { invoiceQueue } from '../../queues/invoice';
 import type { TLineItemExpanded } from '../../store/models';
 import { CheckoutSession } from '../../store/models/checkout-session';
@@ -35,7 +34,7 @@ import { PaymentMethod } from '../../store/models/payment-method';
 import { Price } from '../../store/models/price';
 import { SetupIntent } from '../../store/models/setup-intent';
 import { Subscription } from '../../store/models/subscription';
-import { SubscriptionItem } from '../../store/models/subscription-item';
+import { ensureInvoiceAndItems } from '../../libs/invoice';
 
 type Result = {
   checkoutSession: CheckoutSession;
@@ -401,184 +400,6 @@ export async function ensureInvoiceForCheckout({
   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 });
-  }
-
-  const invoice = await Invoice.create({
-    livemode: props.livemode,
-    number: await customer.getInvoiceNumber(),
-    description: props.description,
-    statement_descriptor: props.statement_descriptor,
-    period_start: props.period_start,
-    period_end: props.period_end,
-
-    auto_advance: props.auto_advance,
-    paid: false,
-    paid_out_of_band: false,
-
-    status: props.status || 'open',
-    collection_method: 'charge_automatically',
-    billing_reason: props.billing_reason,
-
-    currency_id: props.currency_id,
-    customer_id: customer.id,
-    payment_intent_id: props.payment_intent_id || '',
-    subscription_id: subscription?.id,
-    checkout_session_id: props.checkout_session_id || '',
-
-    total: props.total || '0',
-    subtotal: props.total || '0',
-    tax: '0',
-    subtotal_excluding_tax: props.total || '0',
-
-    amount_due: props.amount_due || remaining,
-    amount_paid: props.amount_paid || '0',
-    amount_remaining: props.amount_remaining || remaining,
-    amount_shipping: '0',
-
-    starting_balance: '0',
-    ending_balance: '0',
-    starting_token_balance: result.starting,
-    ending_token_balance: result.ending,
-
-    attempt_count: 0,
-    attempted: false,
-    // next_payment_attempt: undefined,
-
-    custom_fields: props.custom_fields || [],
-    customer_address: customer.address,
-    customer_email: customer.email,
-    customer_name: customer.name,
-    customer_phone: customer.phone,
-
-    discounts: [],
-    total_discount_amounts: [],
-
-    due_date: undefined, // The date on which payment for this invoice is due
-    effective_at: dayjs().unix(), // The date when this invoice is in effect
-    status_transitions: {
-      finalized_at: dayjs().unix(),
-    },
-
-    payment_settings: subscription?.payment_settings,
-    default_payment_method_id: props.default_payment_method_id,
-
-    account_country: '',
-    account_name: '',
-    footer: props.footer || '',
-    metadata: props.metadata || {},
-  });
-
-  // create invoice items: for those require payment this time
-  const subscriptionItems = subscription
-    ? await SubscriptionItem.findAll({ where: { subscription_id: subscription?.id } })
-    : [];
-
-  const 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(),
-      // @ts-ignore
-      description: price.product.name,
-      period: undefined,
-    };
-  };
-
-  const items = await Promise.all(
-    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 InvoiceItem.create({
-        livemode: !!props.livemode,
-        amount: quantity > 0 ? setup.amount : '0',
-        quantity,
-        description: setup.description,
-        period: setup.period,
-        currency_id: props.currency_id,
-        customer_id: customer.id,
-        price_id: price.id,
-        invoice_id: invoice.id,
-        subscription_id: subscription?.id,
-        subscription_item_id: subscriptionItems.find((si) => si.price_id === price.id)?.id,
-        discountable: false,
-        discounts: [],
-        discount_amounts: [],
-        proration: false,
-        proration_details: {},
-        metadata: x.metadata || {},
-      });
-    })
-  );
-
-  return { invoice, items };
-}
-
-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 ensureInvoiceForCollect(invoiceId: string) {
   const invoice = await Invoice.findByPk(invoiceId);
   if (!invoice) {
@@ -717,6 +538,7 @@ export async function getDelegationTxClaim({
     paymentMethod,
     paymentCurrency,
   });
+
   if (mode === 'delegation') {
     tokenRequirements = [];
   }
@@ -863,6 +685,82 @@ export async function getStakeTxClaim({
   throw new Error(`getStakeTxClaim: Payment method ${paymentMethod.type} not supported`);
 }
 
+export async function getOverdraftProtectionStakeTxClaim({
+  userDid,
+  userPk,
+  subscription,
+  paymentCurrency,
+  paymentMethod,
+  stakeAmount,
+}: {
+  userDid: string;
+  userPk: string;
+  subscription: Subscription;
+  paymentCurrency: PaymentCurrency;
+  paymentMethod: PaymentMethod;
+  stakeAmount: string;
+}) {
+  // create staking amount
+  logger.info('getStakeTxClaim', {
+    subscriptionId: subscription.id,
+    paymentCurrencyId: paymentCurrency.id,
+    paymentMethodId: paymentMethod.id,
+    stakeAmount,
+  });
+
+  if (paymentMethod.type === 'arcblock') {
+    // create staking data
+    const client = paymentMethod.getOcapClient();
+    const nonce = `overdraft-protection-${subscription.id}`;
+    const address = await getCustomerStakeAddress(userDid, nonce);
+    const { state } = await client.getStakeState({ address });
+    const data = {
+      type: 'json',
+      value: Object.assign(
+        {
+          appId: wallet.address,
+          subscriptionId: subscription.id,
+        },
+        JSON.parse(state?.data?.value || '{}')
+      ),
+    };
+
+    return {
+      type: 'StakeTx',
+      description: `Stake to complete subscription ${subscription.id} overdraft protection`,
+      partialTx: {
+        from: userDid,
+        pk: userPk,
+        itx: {
+          address,
+          receiver: wallet.address,
+          slashers: [wallet.address],
+          revokeWaitingPeriod: 0,
+          message: `Stake for subscription ${subscription.id} overdraft protection`,
+          nonce,
+          inputs: [],
+          data,
+        },
+        signatures: [],
+      },
+      requirement: {
+        tokens: [{ address: paymentCurrency.contract as string, value: stakeAmount }],
+      },
+      nonce: `stake-${subscription.id}`,
+      meta: {
+        purpose: 'staking',
+        address,
+      },
+      chainInfo: {
+        host: paymentMethod.settings?.arcblock?.api_host as string,
+        id: paymentMethod.settings?.arcblock?.chain_id as string,
+      },
+    };
+  }
+
+  throw new Error(`getStakeTxClaim: Payment method ${paymentMethod.type} not supported`);
+}
+
 export type TokenRequirementArgs = {
   items: TLineItemExpanded[];
   mode: string;
@@ -1045,6 +943,40 @@ export async function ensureSubscriptionForCollectBatch(subscriptionId: string,
   };
 }
 
+export async function ensureSubscriptionForOverdraftProtection(subscriptionId: string, amount: string) {
+  const subscription = await Subscription.findByPk(subscriptionId);
+  if (!subscription) {
+    throw new Error(`Subscription ${subscriptionId} not found when prepare overdraft protection`);
+  }
+
+  const paymentCurrency = await PaymentCurrency.findByPk(subscription.currency_id);
+  if (!paymentCurrency) {
+    throw new Error(`PaymentCurrency ${subscription.currency_id} not found when prepare overdraft protection`);
+  }
+  
+  const paymentMethod = await PaymentMethod.findByPk(paymentCurrency.payment_method_id);
+
+  if (!paymentMethod) {
+    throw new Error(`Payment method not found for subscription ${subscriptionId}`);
+  }
+  if (paymentMethod.type !== 'arcblock') {
+    throw new Error(`Payment method ${paymentMethod.type} not supported for overdraft protection`);
+  }
+
+  const customer = await Customer.findByPk(subscription.customer_id);
+  if (!customer) {
+    throw new Error(`Customer not found for subscription ${subscriptionId}`);
+  }
+
+  return {
+    subscription,
+    paymentCurrency: paymentCurrency as PaymentCurrency,
+    paymentMethod: paymentMethod as PaymentMethod,
+    customer,
+    stakeAmount: fromTokenToUnit(amount, paymentCurrency.decimal).toString(),
+  };
+}
+
 export async function executeOcapTransactions(
   userDid: string,
   userPk: string,
@@ -1052,7 +984,8 @@ export async function executeOcapTransactions(
   paymentMethod: PaymentMethod,
   request: Request,
   subscriptionId?: string,
-  paymentCurrencyContract?: string
+  paymentCurrencyContract?: string,
+  nonce?: string
 ) {
   const client = paymentMethod.getOcapClient();
   const delegation = claims.find((x) => x.type === 'signature' && x.meta?.purpose === 'delegation');
@@ -1089,104 +1022,18 @@ export async function executeOcapTransactions(
     })
   );
 
-  const nonce = subscriptionId || '';
-
   return {
     tx_hash: delegationTxHash,
     payer: userDid,
     type: 'delegate',
     staking: {
       tx_hash: stakingTxHash,
-      address: await getCustomerStakeAddress(userDid, nonce),
+      address: await getCustomerStakeAddress(userDid, nonce || subscriptionId || ''),
     },
     stakingAmount,
   };
 }
 
-export async function ensureStakeInvoice(
-  invoiceProps: { total: string; description?: string; checkout_session_id?: string; currency_id: string; metadata?: any; payment_settings?: any },
-  subscription: Subscription,
-  paymentMethod: PaymentMethod,
-  customer: Customer
-) {
-  if (paymentMethod.type !== 'arcblock') {
-    return;
-  }
-  try {
-    const stakingInvoice = await Invoice.create({
-      livemode: subscription.livemode,
-      number: await customer.getInvoiceNumber(),
-      description: invoiceProps?.description || 'Stake for subscription',
-      statement_descriptor: '',
-      period_start: dayjs().unix(),
-      period_end: subscription.current_period_end,
-
-      auto_advance: false,
-      paid: true,
-      paid_out_of_band: false,
-
-      status: 'paid',
-      collection_method: 'charge_automatically',
-      billing_reason: 'stake',
-
-      currency_id: invoiceProps.currency_id,
-      customer_id: customer.id,
-      payment_intent_id: '',
-      subscription_id: subscription?.id,
-      checkout_session_id: invoiceProps?.checkout_session_id || '',
-
-      total: invoiceProps.total || '0',
-      subtotal: invoiceProps.total || '0',
-      tax: '0',
-      subtotal_excluding_tax: invoiceProps.total || '0',
-
-      amount_due: '0',
-      amount_paid: invoiceProps.total || '0',
-      amount_remaining: '0',
-      amount_shipping: '0',
-
-      starting_balance: '0',
-      ending_balance: '0',
-      starting_token_balance: {},
-      ending_token_balance: {},
-
-      attempt_count: 0,
-      attempted: false,
-      // next_payment_attempt: undefined,
-
-      custom_fields: [],
-      customer_address: customer.address,
-      customer_email: customer.email,
-      customer_name: customer.name,
-      customer_phone: customer.phone,
-
-      discounts: [],
-      total_discount_amounts: [],
-
-      due_date: undefined,
-      effective_at: dayjs().unix(), 
-      status_transitions: {
-        finalized_at: dayjs().unix(),
-      },
-
-      payment_settings: invoiceProps?.payment_settings || subscription?.payment_settings,
-      default_payment_method_id: paymentMethod.id,
-
-      account_country: '',
-      account_name: '',
-      metadata: invoiceProps.metadata || {},
-    });
-    logger.info('create staking invoice success', {
-      stakingInvoice,
-      subscriptionId: subscription?.id,
-      paymentMethod: paymentMethod.id,
-      customerId: customer.id,
-    });
-  } catch (error) {
-    logger.error('ensureStake: create invoice failed', { error, subscriptionId: subscription?.id, paymentMethod: paymentMethod.id, customerId: customer.id });
-  }
-}
-
 
 export async function updateStripeSubscriptionAfterChangePayment(setupIntent: SetupIntent, subscription: Subscription) {
   const { from_method: fromMethodId, to_method: toMethodId } = setupIntent.metadata || {};
@@ -1232,83 +1079,3 @@ export async function updateStripeSubscriptionAfterChangePayment(setupIntent: Se
   }
 }
 
-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 rechargeInvoice = await Invoice.create({
-      livemode: subscription.livemode,
-      number: await customer.getInvoiceNumber(),
-      description: invoiceProps?.description || 'Add funds for subscription',
-      statement_descriptor: '',
-      period_start: dayjs().unix(),
-      period_end: dayjs().unix(),
-
-      auto_advance: false,
-      paid: true,
-      paid_out_of_band: false,
-
-      status: 'paid',
-      collection_method: 'charge_automatically',
-      billing_reason: 'recharge',
-
-      currency_id: invoiceProps.currency_id,
-      customer_id: customer.id,
-      payment_intent_id: '',
-      subscription_id: subscription?.id,
-      checkout_session_id: invoiceProps?.checkout_session_id || '',
-
-      total: invoiceProps.total || '0',
-      subtotal: invoiceProps.total || '0',
-      tax: '0',
-      subtotal_excluding_tax: invoiceProps.total || '0',
-
-      amount_due: '0',
-      amount_paid: invoiceProps.total || '0',
-      amount_remaining: '0',
-      amount_shipping: '0',
-
-      starting_balance: '0',
-      ending_balance: '0',
-      starting_token_balance: {},
-      ending_token_balance: {},
-
-      attempt_count: 0,
-      attempted: false,
-      // next_payment_attempt: undefined,
-
-      custom_fields: [],
-      customer_address: customer.address,
-      customer_email: customer.email,
-      customer_name: customer.name,
-      customer_phone: customer.phone,
-
-      discounts: [],
-      total_discount_amounts: [],
-
-      due_date: undefined,
-      effective_at: dayjs().unix(), 
-      status_transitions: {
-        finalized_at: dayjs().unix(),
-      },
-
-      payment_settings: invoiceProps?.payment_settings || subscription?.payment_settings,
-      default_payment_method_id: paymentMethod.id,
-
-      account_country: '',
-      account_name: '',
-      metadata: invoiceProps.metadata || {},
-    });
-    logger.info('create recharge invoice success', {
-      rechargeInvoice,
-      subscriptionId: subscription?.id,
-      paymentMethod: paymentMethod.id,
-      customerId: customer.id,
-    });
-  } catch (error) {
-    logger.error('ensureRechargeInvoice: create invoice failed', { error, subscriptionId: subscription?.id, paymentMethod: paymentMethod.id, customerId: customer.id });
-  }
-}

package/api/src/routes/connect/subscribe.ts

@@ -12,12 +12,12 @@ import type { Invoice, TLineItemExpanded } from '../../store/models';
 import {
   ensureInvoiceForCheckout,
   ensurePaymentIntent,
-  ensureStakeInvoice,
   executeOcapTransactions,
   getAuthPrincipalClaim,
   getDelegationTxClaim,
   getStakeTxClaim,
 } from './shared';
+import { ensureStakeInvoice } from '../../libs/invoice';
 
 export default {
   action: 'subscription',