payment-kit 1.20.12 → 1.20.14

package/api/src/crons/index.ts

@@ -19,6 +19,7 @@ import {
   stripeSubscriptionCronTime,
   subscriptionCronTime,
   vendorStatusCheckCronTime,
+  vendorReturnScanCronTime,
 } from '../libs/env';
 import logger from '../libs/logger';
 import { startCreditConsumeQueue } from '../queues/credit-consume';
@@ -31,6 +32,7 @@ import { createPaymentStat } from './payment-stat';
 import { SubscriptionTrialWillEndSchedule } from './subscription-trial-will-end';
 import { SubscriptionWillCanceledSchedule } from './subscription-will-canceled';
 import { SubscriptionWillRenewSchedule } from './subscription-will-renew';
+import { scheduleVendorReturnScan } from '../queues/vendors/return-scanner';
 
 function init() {
   Cron.init({
@@ -123,6 +125,12 @@ function init() {
         fn: () => startVendorStatusCheckSchedule(),
         options: { runOnInit: false },
       },
+      {
+        name: 'vendor.return.scan',
+        time: vendorReturnScanCronTime,
+        fn: () => scheduleVendorReturnScan(),
+        options: { runOnInit: false },
+      },
     ],
     onError: (error: Error, name: string) => {
       logger.error('run job failed', { name, error });

package/api/src/libs/env.ts

@@ -15,6 +15,7 @@ export const meteringSubscriptionDetectionCronTime: string =
 export const depositVaultCronTime: string = process.env.DEPOSIT_VAULT_CRON_TIME || '0 */5 * * * *'; // 默认每 5 min 执行一次
 export const creditConsumptionCronTime: string = process.env.CREDIT_CONSUMPTION_CRON_TIME || '0 */10 * * * *'; // 默认每 10 min 执行一次
 export const vendorStatusCheckCronTime: string = process.env.VENDOR_STATUS_CHECK_CRON_TIME || '0 */10 * * * *'; // 默认每 10 min 执行一次
+export const vendorReturnScanCronTime: string = process.env.VENDOR_RETURN_SCAN_CRON_TIME || '0 */10 * * * *'; // 默认每 10 min 执行一次
 export const vendorTimeoutMinutes: number = process.env.VENDOR_TIMEOUT_MINUTES
   ? +process.env.VENDOR_TIMEOUT_MINUTES
   : 10; // 默认 10 分钟超时

package/api/src/libs/vendor-util/adapters/launcher-adapter.ts

@@ -1,4 +1,4 @@
-import { VendorAuth } from '@blocklet/payment-vendor';
+import { Auth as VendorAuth } from '@blocklet/payment-vendor';
 
 import { joinURL } from 'ufo';
 import { ProductVendor } from '../../../store/models';

package/api/src/libs/vendor-util/adapters/types.ts

@@ -73,6 +73,7 @@ export interface ReturnRequestParams {
 export interface ReturnRequestResult {
   status: 'requested' | 'accepted' | 'rejected' | 'failed';
   message?: string;
+  success?: boolean;
 }
 
 export interface CheckOrderStatusParams extends Record<string, any> {}

package/api/src/libs/vendor-util/fulfillment.ts

@@ -206,7 +206,7 @@ export class VendorFulfillmentService {
     } catch (error: any) {
       logger.error('Failed to get vendor adapter', {
         vendorKey,
-        error: error.message,
+        error,
       });
       throw error;
     }

package/api/src/queues/vendors/fulfillment-coordinator.ts

@@ -13,35 +13,7 @@ import { Refund } from '../../store/models/refund';
 import { sequelize } from '../../store/sequelize';
 import { depositVaultQueue } from '../payment';
 
-type VendorInfo = {
-  vendor_id: string;
-  vendor_key: string;
-  order_id: string;
-  status:
-    | 'pending'
-    | 'processing'
-    | 'completed'
-    | 'failed'
-    | 'cancelled'
-    | 'max_retries_exceeded'
-    | 'return_requested'
-    | 'sent';
-  service_url?: string;
-  error_message?: string;
-  amount: string;
-
-  attempts?: number;
-  lastAttemptAt?: string;
-  completedAt?: string;
-  commissionAmount?: string;
-
-  returnRequest?: {
-    reason: string;
-    requestedAt: string;
-    status: 'pending' | 'accepted' | 'rejected';
-    returnDetails?: string;
-  };
-};
+export type VendorInfo = NonNullable<CheckoutSession['vendor_info']>[number];
 
 interface CoordinatorJob {
   checkoutSessionId: string;

package/api/src/queues/vendors/return-processor.ts

@@ -0,0 +1,184 @@
+import logger from '../../libs/logger';
+import createQueue from '../../libs/queue';
+import { VendorFulfillmentService } from '../../libs/vendor-util/fulfillment';
+import { CheckoutSession } from '../../store/models';
+import { VendorInfo } from './fulfillment-coordinator';
+
+type ReturnProcessorJob = {
+  checkoutSessionId: string;
+};
+
+export const vendorReturnProcessorQueue = createQueue<ReturnProcessorJob>({
+  name: 'vendor-return-processor',
+  onJob: handleReturnProcessorJob,
+  options: {
+    concurrency: 1,
+    maxRetries: 2,
+    retryDelay: 30 * 1000,
+  },
+});
+
+async function handleReturnProcessorJob(job: ReturnProcessorJob): Promise<void> {
+  const { checkoutSessionId } = job;
+
+  logger.info('Starting vendor return processor job', {
+    checkoutSessionId,
+  });
+
+  try {
+    const checkoutSession = await CheckoutSession.findByPk(checkoutSessionId);
+
+    if (!checkoutSession) {
+      logger.warn('CheckoutSession not found', { checkoutSessionId });
+      return;
+    }
+
+    const vendorInfoList = checkoutSession.vendor_info as VendorInfo[];
+    let hasChanges = false;
+
+    let i = -1;
+    for (const vendor of vendorInfoList) {
+      i++;
+      // Only process vendors with 'completed' status
+      if (vendor.status !== 'completed') {
+        logger.info('Skipping vendor return because status is not completed', {
+          checkoutSessionId,
+          vendorId: vendor.vendor_id,
+          orderId: vendor.order_id,
+          status: vendor.status,
+        });
+        // eslint-disable-next-line no-continue
+        continue;
+      }
+
+      try {
+        logger.info('Processing vendor return', {
+          checkoutSessionId,
+          vendorId: vendor.vendor_id,
+          orderId: vendor.order_id,
+        });
+
+        // eslint-disable-next-line no-await-in-loop
+        const returnResult = await callVendorReturn(vendor, checkoutSession);
+
+        if (returnResult.success) {
+          // Return successful, update status to 'returned'
+          vendorInfoList[i] = {
+            ...vendor,
+            status: 'returned',
+            lastAttemptAt: new Date().toISOString(),
+          };
+          hasChanges = true;
+
+          logger.info('Vendor return successful', {
+            checkoutSessionId,
+            vendorId: vendor.vendor_id,
+            orderId: vendor.order_id,
+          });
+        } else {
+          // Return failed, keep 'completed' status for next scan retry
+          vendorInfoList[i] = {
+            ...vendor,
+            lastAttemptAt: new Date().toISOString(),
+            error_message: returnResult.message || 'Return request failed',
+          };
+
+          logger.warn('Vendor return failed', {
+            checkoutSessionId,
+            vendorId: vendor.vendor_id,
+            orderId: vendor.order_id,
+            error: returnResult.message,
+          });
+        }
+      } catch (error: any) {
+        logger.error('Error processing vendor return', {
+          checkoutSessionId,
+          vendorId: vendor.vendor_id,
+          orderId: vendor.order_id,
+          error: error.message,
+        });
+
+        // Record error but keep status unchanged for retry
+        vendorInfoList[i] = {
+          ...vendor,
+          lastAttemptAt: new Date().toISOString(),
+          error_message: error.message,
+        };
+        hasChanges = true;
+      }
+    }
+
+    // Update vendor_info if there are changes
+    if (hasChanges) {
+      await checkoutSession.update({ vendor_info: vendorInfoList });
+    }
+
+    // Check if all vendors have been returned
+    const allReturned = vendorInfoList.every((vendor) => vendor.status === 'returned');
+
+    if (allReturned && checkoutSession.fulfillment_status !== 'returned') {
+      await checkoutSession.update({ fulfillment_status: 'returned' });
+
+      logger.info('All vendors returned, updated fulfillment status to returned', {
+        checkoutSessionId,
+        totalVendors: vendorInfoList.length,
+      });
+    }
+
+    logger.info('Vendor return processor job completed', {
+      checkoutSessionId,
+      totalVendors: vendorInfoList.length,
+      allReturned,
+      hasChanges,
+    });
+  } catch (error: any) {
+    logger.error('Vendor return processor job failed', {
+      checkoutSessionId,
+      error,
+    });
+    throw error;
+  }
+}
+
+async function callVendorReturn(
+  vendor: VendorInfo,
+  checkoutSession: CheckoutSession
+): Promise<{ success: boolean; message?: string }> {
+  try {
+    const vendorAdapter = await VendorFulfillmentService.getVendorAdapter(vendor.vendor_key);
+
+    if (!vendorAdapter) {
+      return {
+        success: false,
+        message: `No adapter found for vendor: ${vendor.vendor_id}`,
+      };
+    }
+
+    const returnResult = await vendorAdapter.requestReturn({
+      orderId: vendor.order_id,
+      reason: 'Subscription canceled',
+      paymentIntentId: checkoutSession.payment_intent_id || '',
+      customParams: {
+        checkoutSessionId: checkoutSession.id,
+        subscriptionId: checkoutSession.subscription_id,
+        vendorKey: vendor.vendor_key,
+      },
+    });
+
+    return {
+      success: returnResult.success || false,
+      message: returnResult.message,
+    };
+  } catch (error: any) {
+    logger.error('Failed to call vendor return API', {
+      vendorId: vendor.vendor_id,
+      orderId: vendor.order_id,
+      error: error.message,
+    });
+
+    return {
+      success: false,
+      message: error.message,
+    };
+  }
+}

package/api/src/queues/vendors/return-scanner.ts

@@ -0,0 +1,119 @@
+import { Op } from 'sequelize';
+import logger from '../../libs/logger';
+import createQueue from '../../libs/queue';
+import { CheckoutSession, Subscription } from '../../store/models';
+import { vendorReturnProcessorQueue } from './return-processor';
+import { VendorInfo } from './fulfillment-coordinator';
+
+export const vendorReturnScannerQueue = createQueue({
+  name: 'vendor-return-scanner',
+  onJob: handleReturnScannerJob,
+  options: {
+    concurrency: 1,
+    maxRetries: 3,
+    retryDelay: 60 * 1000,
+  },
+});
+
+async function handleReturnScannerJob(): Promise<void> {
+  try {
+    const sessionsNeedingReturn = await findSessionsNeedingVendorReturn();
+    if (sessionsNeedingReturn.length === 0) {
+      logger.info('No checkout sessions needing vendor return');
+      return;
+    }
+
+    logger.info('Found checkout sessions needing vendor return', {
+      count: sessionsNeedingReturn.length,
+      sessionIds: sessionsNeedingReturn.map((s) => s.id),
+    });
+
+    for (const session of sessionsNeedingReturn) {
+      const id = `vendor-return-process-${session.id}`;
+      // eslint-disable-next-line no-await-in-loop
+      const exists = await vendorReturnProcessorQueue.get(id);
+      if (!exists) {
+        vendorReturnProcessorQueue.push({
+          id,
+          job: {
+            checkoutSessionId: session.id,
+          },
+        });
+      }
+    }
+  } catch (error: any) {
+    logger.error('Vendor return scanner job failed', {
+      error,
+    });
+    throw error;
+  }
+}
+
+async function findSessionsNeedingVendorReturn(): Promise<CheckoutSession[]> {
+  try {
+    // First, find canceled subscriptions
+    const canceledSubscriptions = await Subscription.findAll({
+      where: { status: 'canceled' },
+      attributes: ['id'],
+    });
+
+    const canceledSubscriptionIds = canceledSubscriptions.map((sub) => sub.id);
+
+    // Find checkout sessions with completed fulfillment and canceled subscriptions
+    const readyToReturnSessions = await CheckoutSession.findAll({
+      where: {
+        fulfillment_status: 'completed',
+        subscription_id: { [Op.in]: canceledSubscriptionIds },
+      },
+      order: [['updated_at', 'DESC']],
+      limit: 100,
+    });
+
+    // Find checkout sessions already in returning status
+    const returningSessions = await CheckoutSession.findAll({
+      where: {
+        fulfillment_status: 'returning',
+        subscription_id: { [Op.ne]: null as any },
+      },
+      order: [['updated_at', 'DESC']],
+      limit: 100,
+    });
+
+    // Update canceled sessions to returning status
+    if (readyToReturnSessions.length > 0) {
+      await CheckoutSession.update(
+        {
+          fulfillment_status: 'returning',
+        },
+        {
+          where: {
+            id: { [Op.in]: readyToReturnSessions.map((s) => s.id) },
+          },
+        }
+      );
+    }
+
+    const sessions = [...readyToReturnSessions, ...returningSessions];
+
+    // Filter sessions that have vendors needing return
+    const filteredSessions = sessions.filter((session) => {
+      const vendorInfoList = session.vendor_info as VendorInfo[];
+
+      if (!vendorInfoList || vendorInfoList.length === 0) {
+        return false;
+      }
+      const hasVendorNeedingReturn = vendorInfoList.some((vendor) => vendor.status === 'completed');
+      return hasVendorNeedingReturn;
+    });
+
+    return filteredSessions;
+  } catch (error: any) {
+    logger.error('Failed to find sessions needing vendor return', { error });
+    throw error;
+  }
+}
+
+export function scheduleVendorReturnScan(): void {
+  const scanId = `scan-${Date.now()}`;
+  vendorReturnScannerQueue.push({ id: scanId, job: {} });
+}

package/api/src/queues/vendors/status-check.ts

@@ -1,5 +1,5 @@
 import { joinURL } from 'ufo';
-import { VendorAuth } from '@blocklet/payment-vendor';
+import { Auth as VendorAuth } from '@blocklet/payment-vendor';
 import createQueue from '../../libs/queue';
 import { CheckoutSession } from '../../store/models/checkout-session';
 import { ProductVendor } from '../../store/models';

package/api/src/routes/checkout-sessions.ts

@@ -668,7 +668,9 @@ const getBeneficiaryName = async (beneficiary: PaymentBeneficiary) => {
   return beneficiary.name || (await getUserOrAppInfo(beneficiary.address || ''))?.name || beneficiary.address;
 };
 
-export async function getCrossSellItem(checkoutSession: CheckoutSession) {
+export async function getCrossSellItem(
+  checkoutSession: CheckoutSession
+): Promise<{ error?: string } | (TPriceExpanded & { product: any; error?: string })> {
   // FIXME: perhaps we can support cross sell even if the current session have multiple items
   if (checkoutSession.line_items.length > 1) {
     return { error: 'Cross sell not supported for checkoutSession with multiple line items' };
@@ -2334,8 +2336,12 @@ router.put('/:id/expire', auth, ensureCheckoutSessionOpen, async (req, res) => {
 router.get('/:id/cross-sell', user, ensureCheckoutSessionOpen, async (req, res) => {
   try {
     const checkoutSession = req.doc as CheckoutSession;
+    const skipError = req.query.skipError === 'true';
     const result = await getCrossSellItem(checkoutSession);
-    // @ts-ignore
+
+    if (skipError && result.error) {
+      return res.status(200).json(result);
+    }
     return res.status(result.error ? 400 : 200).json(result);
   } catch (err) {
     logger.error(err);
@@ -2633,6 +2639,10 @@ router.post('/:id/recalculate-promotion', user, ensureCheckoutSessionOpen, async
       return res.status(400).json({ error: 'Coupon no longer valid' });
     }
 
+    const now = dayjs().unix();
+    const trialSetup = getSubscriptionTrialSetup(checkoutSession.subscription_data as any, currency.id);
+    const isTrialing = trialSetup.trialInDays > 0 || trialSetup.trialEnd > now;
+
     // Apply discount with new currency
     const discountResult = await applyDiscountsToLineItems({
       lineItems: expandedItems,
@@ -2640,6 +2650,9 @@ router.post('/:id/recalculate-promotion', user, ensureCheckoutSessionOpen, async
       couponId,
       customerId: customer.id,
       currency,
+      billingContext: {
+        trialing: isTrialing,
+      },
     });
 
     // Check if discount can still be applied with the new currency

package/api/src/routes/coupons.ts

@@ -373,6 +373,13 @@ router.put('/:id', auth, async (req, res) => {
     return res.status(404).json({ error: 'Coupon not found' });
   }
 
+  if (req.body.metadata) {
+    const { error: metadataError } = MetadataSchema.validate(req.body.metadata);
+    if (metadataError) {
+      return res.status(400).json({ error: `metadata invalid: ${metadataError.message}` });
+    }
+  }
+
   if (coupon.locked) {
     const allowedUpdates = pick(value, ['name', 'metadata', 'description']);
     if (Object.keys(allowedUpdates).length === 0) {

package/api/src/routes/credit-grants.ts

@@ -11,6 +11,7 @@ import { CreditGrant, Customer, PaymentCurrency, Price, Subscription } from '../
 import { createCreditGrant } from '../libs/credit-grant';
 import { getMeterPriceIdsFromSubscription } from '../libs/subscription';
 import { blocklet } from '../libs/auth';
+import { formatMetadata } from '../libs/util';
 
 const router = Router();
 const auth = authenticate<CreditGrant>({ component: true, roles: ['owner', 'admin'] });
@@ -264,7 +265,13 @@ router.put('/:id', auth, async (req, res) => {
   if (error) {
     return res.status(400).json({ error: `Credit grant update request invalid: ${error.message}` });
   }
-  await creditGrant.update({ metadata: req.body.metadata });
+  if (req.body.metadata) {
+    const { error: metadataError } = MetadataSchema.validate(req.body.metadata);
+    if (metadataError) {
+      return res.status(400).json({ error: `metadata invalid: ${metadataError.message}` });
+    }
+  }
+  await creditGrant.update({ metadata: formatMetadata(req.body.metadata) });
   return res.json({ success: true });
 });