payment-kit 1.20.10 → 1.20.12

package/README.md

@@ -1,46 +1,47 @@
 # Payment Kit
 
-The decentralized stripe for blocklet platform.
+The decentralized Stripe for the Blocklet platform.
 
 ## Contribution
 
 ### Development
 
-1. clone the repo
-2. run `make build`
-3. run `cd blocklets/core && blocklet dev`
+1. Clone the repository
+2. Run `make build`
+3. Run `cd blocklets/core && blocklet dev`
 
-##### when error
+#### Troubleshooting
 
-1. pre-start error component xxx is not running or unreachable
+**Error: "pre-start error component xxx is not running or unreachable"**
 
-- create .env.local file in this root
-  - add BLOCKLET_DEV_APP_DID="did:abt:your payment kit server did"
-  - add BLOCKLET_DEV_MOUNT_POINT="/example"
-- copy .env.local to be under the /core
-  - edit BLOCKLET_DEV_MOUNT_POINT="/"
+- Create a `.env.local` file in the project root
+  - Add `BLOCKLET_DEV_APP_DID="did:abt:your payment kit server did"`
+  - Add `BLOCKLET_DEV_MOUNT_POINT="/example"`
+- Copy `.env.local` to the `/core` directory
+  - Edit `BLOCKLET_DEV_MOUNT_POINT="/"`
 
-2. Insufficient fund to pay for tx cost from xxx, expected 1.0020909, got 0
-   - copy BLOCKLET_DEV_APP_DID
-   - transfer 2 TBA in your DID Wallet to your copied address
+**Error: "Insufficient funds to pay for transaction cost from xxx, expected 1.0020909, got 0"**
+
+- Copy the `BLOCKLET_DEV_APP_DID`
+- Transfer 2 TBA from your DID Wallet to the copied address
 
 ### Debug Stripe
 
-1. Install and login with instructions from: https://stripe.com/docs/stripe-cli
-2. Start your local payment-kit server, get it's port
+1. Install and log in following the instructions at: https://stripe.com/docs/stripe-cli
+2. Start your local Payment Kit server and note its port
 3. Run `stripe listen --forward-to http://127.0.0.1:8188/api/integrations/stripe/webhook --log-level=debug --latest`
 
 ### Test Stripe
 
-Invoices for subscriptions are not finalized automatically. You can use stripe postman collection to finalize it and then confirm the payment.
+Invoices for subscriptions are not finalized automatically. You can use the Stripe Postman collection to finalize them and then confirm the payment.
 
 ### Easter Eggs
 
-None public environment variables used in the code, can change the behavior of the payment-kit.
+Non-public environment variables used in the code that can change the behavior of Payment Kit:
 
-- PAYMENT_CHANGE_LOCKED_PRICE: allow change locked price, must be set to "1" to work
-- PAYMENT_RELOAD_SUBSCRIPTION_JOBS: reload subscription jobs on start, must be set to "1" to work
-- PAYMENT_BILLING_THRESHOLD: global default billing threshold, must be a number
-- PAYMENT_MIN_STAKE_AMOUNT: global min stake amount limit, must be a number
-- PAYMENT_DAYS_UNTIL_DUE: global default days until due, must be a number
-- PAYMENT_DAYS_UNTIL_CANCEL: global default days until cancel, must be a number
+- `PAYMENT_CHANGE_LOCKED_PRICE`: Allows changing locked price (must be set to "1" to enable)
+- `PAYMENT_RELOAD_SUBSCRIPTION_JOBS`: Reloads subscription jobs on start (must be set to "1" to enable)
+- `PAYMENT_BILLING_THRESHOLD`: Global default billing threshold (must be a number)
+- `PAYMENT_MIN_STAKE_AMOUNT`: Global minimum stake amount limit (must be a number)
+- `PAYMENT_DAYS_UNTIL_DUE`: Global default days until due (must be a number)
+- `PAYMENT_DAYS_UNTIL_CANCEL`: Global default days until cancellation (must be a number)

package/api/src/index.ts

@@ -26,6 +26,7 @@ import { initEventBroadcast } from './libs/ws';
 import { startCheckoutSessionQueue } from './queues/checkout-session';
 import { startCreditConsumeQueue } from './queues/credit-consume';
 import { startCreditGrantQueue } from './queues/credit-grant';
+import { startDiscountStatusQueue } from './queues/discount-status';
 import { startEventQueue } from './queues/event';
 import { startInvoiceQueue } from './queues/invoice';
 import { startNotificationQueue } from './queues/notification';
@@ -135,6 +136,7 @@ export const server = app.listen(port, (err?: any) => {
   startRefundQueue().then(() => logger.info('refund queue started'));
   startCreditConsumeQueue().then(() => logger.info('credit queue started'));
   startCreditGrantQueue().then(() => logger.info('credit grant queue started'));
+  startDiscountStatusQueue().then(() => logger.info('discount status queue started'));
   startUploadBillingInfoListener();
 
   if (process.env.BLOCKLET_MODE === 'production') {

package/api/src/integrations/stripe/handlers/invoice.ts

@@ -4,6 +4,7 @@ import pick from 'lodash/pick';
 import pWaitFor from 'p-wait-for';
 import type Stripe from 'stripe';
 
+import type { WhereOptions } from 'sequelize';
 import { checkUsageReportEmpty } from '../../../libs/subscription';
 import { createEvent } from '../../../libs/audit';
 import { getLock } from '../../../libs/lock';
@@ -12,6 +13,7 @@ import {
   AutoRechargeConfig,
   CheckoutSession,
   Customer,
+  Discount,
   Invoice,
   InvoiceItem,
   PaymentMethod,
@@ -24,6 +26,11 @@ import { handleSubscriptionOnPaymentFailure } from './subscription';
 
 export async function handleStripeInvoicePaid(invoice: Invoice, event: TEventExpanded) {
   logger.info('invoice paid on stripe event', { locale: invoice.id });
+  const processDiscounts = await processInvoiceDiscounts(
+    event.data.object,
+    invoice.subscription_id || '',
+    invoice.checkout_session_id || ''
+  );
   await invoice.update({
     status: 'paid',
     ...pick(event.data.object, [
@@ -37,12 +44,38 @@ export async function handleStripeInvoicePaid(invoice: Invoice, event: TEventExp
       'subtotal_excluding_tax',
       'subtotal',
       'tax',
-      'total_discount_amounts',
       'total',
     ]),
+    total_discount_amounts: processDiscounts,
   });
 }
 
+const processInvoiceDiscounts = async (stripeInvoice: any, subscriptionId: string, checkoutSessionId: string) => {
+  const discountFilter: WhereOptions = {};
+  if (checkoutSessionId) {
+    discountFilter.checkout_session_id = checkoutSessionId;
+  }
+  if (subscriptionId) {
+    discountFilter.subscription_id = subscriptionId;
+  }
+  const discount =
+    stripeInvoice.total_discount_amounts && Object.keys(discountFilter).length > 0
+      ? await Discount.findOne({
+          where: discountFilter,
+        })
+      : null;
+  const processDiscounts = stripeInvoice.total_discount_amounts
+    ? stripeInvoice.total_discount_amounts.map((d: any) => {
+        return {
+          stripeDiscount: d.discount,
+          discount: discount?.id || d.discount,
+          amount: d.amount,
+        };
+      })
+    : null;
+  return processDiscounts;
+};
+
 export function getStripeInvoicePeriod(invoice: any) {
   const lineItem: TInvoiceItem = (invoice.lines.data || []).find((x: any) => !x.proration && x.type === 'subscription');
   if (lineItem && lineItem.period) {
@@ -71,6 +104,11 @@ export async function syncStripeInvoice(invoice: Invoice) {
   const client = await method.getStripeClient();
   const stripeInvoice = await client.invoices.retrieve(invoice.metadata.stripe_id);
   if (stripeInvoice) {
+    const processDiscounts = await processInvoiceDiscounts(
+      stripeInvoice,
+      invoice.subscription_id || '',
+      invoice.checkout_session_id || ''
+    );
     await invoice.update(
       // @ts-ignore
       merge(
@@ -89,7 +127,10 @@ export async function syncStripeInvoice(invoice: Invoice) {
           'total_discount_amounts',
           'total',
         ]),
-        getStripeInvoicePeriod(stripeInvoice)
+        getStripeInvoicePeriod(stripeInvoice),
+        {
+          total_discount_amounts: processDiscounts,
+        }
       )
     );
     logger.info('stripe invoice synced', { locale: invoice.id, remote: stripeInvoice.id });
@@ -122,6 +163,19 @@ export async function ensureStripeInvoice(stripeInvoice: any, subscription: Subs
     return invoice;
   }
 
+  const processTotalDiscounts = await processInvoiceDiscounts(
+    stripeInvoice,
+    subscription.id,
+    checkoutSession?.id || ''
+  );
+
+  let processDiscounts = stripeInvoice.discounts;
+  if (stripeInvoice.discounts && stripeInvoice.discounts.length > 0) {
+    if (processTotalDiscounts) {
+      processDiscounts = processTotalDiscounts.map((d: any) => d?.discount);
+    }
+  }
+
   const invoiceNumber = await customer.getInvoiceNumber();
   // @ts-ignore
   invoice = await Invoice.create({
@@ -157,11 +211,11 @@ export async function ensureStripeInvoice(stripeInvoice: any, subscription: Subs
       'subtotal_excluding_tax',
       'subtotal',
       'tax',
-      'total_discount_amounts',
       'total',
       'last_finalization_error',
     ]),
-
+    discounts: processDiscounts,
+    total_discount_amounts: processTotalDiscounts,
     currency_id: subscription.currency_id,
     customer_id: subscription.customer_id,
     default_payment_method_id: subscription.default_payment_method_id as string,
@@ -173,6 +227,7 @@ export async function ensureStripeInvoice(stripeInvoice: any, subscription: Subs
     payment_settings: subscription.payment_settings,
     metadata: {
       stripe_id: stripeInvoice.id,
+      stripe_discounts: stripeInvoice.discounts,
     },
   });
   if (checkoutSession) {
@@ -216,7 +271,10 @@ export async function ensureStripeInvoice(stripeInvoice: any, subscription: Subs
         },
       });
 
-      logger.info('stripe invoice items mirrored', { local: item.id, remote: line.id });
+      logger.info('stripe invoice items mirrored', {
+        local: item.id,
+        remote: line.id,
+      });
       return item;
     })
   );

package/api/src/integrations/stripe/handlers/payment-intent.ts

@@ -132,6 +132,7 @@ const waitForStripePaymentMirrored = (stripeInvoiceId: string) => {
 
 export async function handlePaymentIntentEvent(event: TEventExpanded, client: Stripe) {
   const localIntentId = event.data.object.metadata?.id;
+
   if (!localIntentId) {
     // We only handle payment_intents created from subscriptions
     if (event.data.object.invoice) {

package/api/src/integrations/stripe/resource.ts

@@ -7,13 +7,14 @@ import pick from 'lodash/pick';
 import { Op } from 'sequelize';
 
 import logger from '../../libs/logger';
-import { getPriceUintAmountByCurrency } from '../../libs/session';
 import { getSubscriptionItemPrice } from '../../libs/subscription';
 import { sleep } from '../../libs/util';
 import {
   AutoRechargeConfig,
   CheckoutSession,
   Customer,
+  Discount,
+  Coupon,
   Invoice,
   InvoiceItem,
   PaymentCurrency,
@@ -28,6 +29,7 @@ import {
 import { syncStripeInvoice } from './handlers/invoice';
 import { syncStripePayment } from './handlers/payment-intent';
 import { getLock } from '../../libs/lock';
+import { getPriceUintAmountByCurrency } from '../../libs/price';
 
 export async function ensureStripeProduct(internal: Product, method: PaymentMethod) {
   const client = method.getStripeClient();
@@ -281,7 +283,8 @@ export async function ensureStripeSubscription(
     stripeSubscription = await client.subscriptions.retrieve(internal.payment_details.stripe.subscription_id, {
       expand: ['latest_invoice.payment_intent', 'pending_setup_intent'],
     });
-    // FIXME: update?
+    // Handle subscription discount updates
+    await updateSubscriptionDiscounts(client, stripeSubscription, internal, method, currency);
   } else {
     const customer = await ensureStripePaymentCustomer(internal, method);
     const prices = await Promise.all(
@@ -327,6 +330,17 @@ export async function ensureStripeSubscription(
       props.trial_end = trialEnd;
     }
 
+    // Handle discounts for subscription
+    const discounts = await getSubscriptionDiscounts(internal, method, currency);
+    if (discounts.length > 0) {
+      props.discounts = discounts;
+      logger.info('Applied discounts to Stripe subscription', {
+        subscription_id: internal.id,
+        discounts: discounts.map((d) => d.coupon),
+        discount_count: discounts.length,
+      });
+    }
+
     stripeSubscription = await client.subscriptions.create(props);
     logger.info('stripe subscription created', { local: internal.id, remote: stripeSubscription.id });
 
@@ -400,6 +414,243 @@ export async function forwardUsageRecordToStripe(
   return result;
 }
 
+/**
+ * Get all discounts associated with a subscription and create Stripe coupons
+ */
+async function getSubscriptionDiscounts(
+  subscription: Subscription,
+  method: PaymentMethod,
+  currency: PaymentCurrency
+): Promise<{ coupon: string }[]> {
+  const discounts = (await Discount.findAll({
+    where: {
+      subscription_id: subscription.id,
+    },
+    include: [
+      {
+        model: Coupon,
+        as: 'coupon',
+        required: true,
+        where: {
+          valid: true,
+        },
+      },
+    ],
+  })) as (Discount & { coupon: Coupon })[];
+
+  const stripeDiscounts = [];
+
+  for (const discount of discounts) {
+    try {
+      const stripeCouponId = await createStripeSubscriptionCoupon(discount.coupon, subscription.id, method, currency);
+      stripeDiscounts.push({ coupon: stripeCouponId });
+
+      logger.info('Created Stripe coupon for subscription', {
+        local_coupon: discount.coupon_id,
+        stripe_coupon: stripeCouponId,
+        subscription_id: subscription.id,
+      });
+    } catch (error) {
+      logger.error('Failed to create Stripe coupon for subscription', {
+        discount_id: discount.id,
+        coupon_id: discount.coupon_id,
+        subscription_id: subscription.id,
+        error: error.message,
+      });
+    }
+  }
+
+  return stripeDiscounts;
+}
+
+/**
+ * Update subscription discounts by managing existing and new discounts
+ * Since Stripe doesn't allow direct discount updates on subscriptions,
+ * we need to use discount deletion and application approach
+ */
+async function updateSubscriptionDiscounts(
+  client: any,
+  stripeSubscription: any,
+  subscription: Subscription,
+  method: PaymentMethod,
+  currency: PaymentCurrency
+): Promise<void> {
+  try {
+    const newDiscounts = await getSubscriptionDiscounts(subscription, method, currency);
+    const existingDiscounts = stripeSubscription.discounts || [];
+
+    const existingCouponIds = existingDiscounts.map((d: any) => d.coupon?.id).filter(Boolean);
+    const newCouponIds = newDiscounts.map((d: any) => d.coupon);
+
+    const hasChanges =
+      existingCouponIds.length !== newCouponIds.length ||
+      !existingCouponIds.every((id: string) => newCouponIds.includes(id));
+
+    if (!hasChanges) {
+      logger.info('No discount changes needed for subscription', {
+        subscription_id: subscription.id,
+        stripe_subscription_id: stripeSubscription.id,
+      });
+      return;
+    }
+
+    // Remove existing discounts (Stripe subscriptions typically have only one discount)
+    if (existingDiscounts.length > 0) {
+      try {
+        await client.subscriptions.deleteDiscount(stripeSubscription.id);
+        logger.info('Removed existing discounts from subscription', {
+          subscription_id: subscription.id,
+          stripe_subscription_id: stripeSubscription.id,
+          removed_count: existingDiscounts.length,
+        });
+      } catch (error) {
+        logger.error('Failed to remove discounts from subscription', {
+          subscription_id: subscription.id,
+          stripe_subscription_id: stripeSubscription.id,
+          error: error.message,
+        });
+      }
+    }
+
+    // Apply new discounts using the discounts field
+    if (newDiscounts.length > 0) {
+      try {
+        await client.subscriptions.update(stripeSubscription.id, {
+          discounts: newDiscounts,
+        });
+
+        logger.info('Applied new discounts to subscription', {
+          subscription_id: subscription.id,
+          stripe_subscription_id: stripeSubscription.id,
+          discounts: newDiscounts.map((d) => d.coupon),
+          discount_count: newDiscounts.length,
+        });
+      } catch (error) {
+        logger.error('Failed to apply discounts to subscription', {
+          subscription_id: subscription.id,
+          stripe_subscription_id: stripeSubscription.id,
+          discounts: newDiscounts,
+          error: error.message,
+        });
+      }
+    }
+  } catch (error) {
+    logger.error('Failed to update subscription discounts', {
+      subscription_id: subscription.id,
+      stripe_subscription_id: stripeSubscription.id,
+      error: error.message,
+    });
+    throw error;
+  }
+}
+
+/**
+ * Create a Stripe coupon specifically for a subscription with max_redemptions = 1
+ */
+async function createStripeSubscriptionCoupon(
+  localCoupon: Coupon,
+  subscriptionId: string,
+  method: PaymentMethod,
+  currency?: PaymentCurrency
+): Promise<string> {
+  const client = method.getStripeClient();
+
+  // Check if coupon already exists for this subscription
+  const existingCouponId = `${localCoupon.id}_sub_${subscriptionId.slice(-8)}`;
+  try {
+    const existingCoupon = await client.coupons.retrieve(existingCouponId);
+    if (existingCoupon) {
+      logger.info('Stripe coupon already exists for subscription', {
+        local_coupon_id: localCoupon.id,
+        stripe_coupon_id: existingCoupon.id,
+        subscription_id: subscriptionId,
+      });
+      return existingCoupon.id;
+    }
+  } catch (error) {
+    logger.error('Failed to retrieve Stripe coupon for subscription', {
+      local_coupon_id: localCoupon.id,
+      subscription_id: subscriptionId,
+      error,
+    });
+  }
+  // Prepare coupon data
+  const couponData: any = {
+    id: existingCouponId, // Use predictable ID
+    name: `sub_coupon_${localCoupon.id}`,
+    duration: localCoupon.duration as 'once' | 'forever' | 'repeating',
+    max_redemptions: 1, // Limit to this subscription only
+    metadata: {
+      appPid: env.appPid,
+      local_coupon_id: localCoupon.id,
+      subscription_id: subscriptionId,
+      created_for: 'subscription',
+    },
+  };
+
+  // Add duration in months for repeating coupons
+  if (localCoupon.duration === 'repeating' && localCoupon.duration_in_months) {
+    couponData.duration_in_months = localCoupon.duration_in_months;
+  }
+
+  // Add discount amount - either percent_off or amount_off
+  if (localCoupon.percent_off && localCoupon.percent_off > 0) {
+    couponData.percent_off = localCoupon.percent_off;
+  } else if (localCoupon.amount_off && localCoupon.amount_off !== '0') {
+    couponData.amount_off = Number(localCoupon.amount_off || '0');
+
+    // Get currency for fixed amount discounts
+    let targetCurrency = currency;
+    if (!targetCurrency && localCoupon.currency_id) {
+      targetCurrency = (await PaymentCurrency.findByPk(localCoupon.currency_id)) || undefined;
+    }
+
+    if (targetCurrency) {
+      couponData.currency = targetCurrency.symbol.toLowerCase();
+    } else {
+      // Fallback to USD if no currency specified
+      couponData.currency = 'usd';
+      logger.warn('No currency specified for fixed amount coupon, defaulting to USD', {
+        local_coupon_id: localCoupon.id,
+        subscription_id: subscriptionId,
+      });
+    }
+  } else {
+    // Default to 0% discount if neither percent_off nor amount_off is set
+    couponData.percent_off = 0;
+    logger.warn('Coupon has no discount amount set, defaulting to 0%', {
+      local_coupon_id: localCoupon.id,
+      subscription_id: subscriptionId,
+    });
+  }
+
+  try {
+    const stripeCoupon = await client.coupons.create(couponData);
+
+    logger.info('Created Stripe coupon for subscription', {
+      local_coupon_id: localCoupon.id,
+      stripe_coupon_id: stripeCoupon.id,
+      subscription_id: subscriptionId,
+      coupon_name: stripeCoupon.name,
+      duration: stripeCoupon.duration,
+      percent_off: stripeCoupon.percent_off,
+      amount_off: stripeCoupon.amount_off,
+      currency: stripeCoupon.currency,
+      max_redemptions: stripeCoupon.max_redemptions,
+    });
+
+    return stripeCoupon.id;
+  } catch (error) {
+    logger.error('Failed to create Stripe coupon for subscription', {
+      local_coupon_id: localCoupon.id,
+      subscription_id: subscriptionId,
+      coupon_data: couponData,
+      error,
+    });
+    throw error;
+  }
+}
+
 export async function batchHandleStripeInvoices() {
   const stripeMethods = await PaymentMethod.findAll({ where: { type: 'stripe' } });
   if (stripeMethods.length === 0) {

package/api/src/libs/currency.ts

@@ -0,0 +1,31 @@
+import { fromTokenToUnit, fromUnitToToken } from '@ocap/util';
+import { PaymentCurrency } from '../store/models';
+import { trimDecimals } from './math-utils';
+
+export async function formatCurrencyToken(amount: string, currencyId: string) {
+  if (!amount) {
+    return '0';
+  }
+  if (!currencyId) {
+    return amount;
+  }
+  const currency = await PaymentCurrency.findByPk(currencyId);
+  if (!currency) {
+    throw new Error(`Currency ${currencyId} not found`);
+  }
+  return fromUnitToToken(trimDecimals(amount || '0', currency.decimal), currency.decimal);
+}
+
+export async function formatCurrencyUnit(amount: string, currencyId: string) {
+  if (!amount) {
+    return '0';
+  }
+  if (!currencyId) {
+    return amount;
+  }
+  const currency = await PaymentCurrency.findByPk(currencyId);
+  if (!currency) {
+    throw new Error(`Currency ${currencyId} not found`);
+  }
+  return fromTokenToUnit(amount || '0', currency.decimal).toString();
+}