payment-kit 1.20.12 → 1.20.13

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/vendor.ts

@@ -1,7 +1,8 @@
+import { getUrl } from '@blocklet/sdk/lib/component';
 import { Router } from 'express';
 import Joi from 'joi';
 
-import { VendorAuth } from '@blocklet/payment-vendor';
+import { Auth as VendorAuth, middleware } from '@blocklet/payment-vendor';
 import { joinURL } from 'ufo';
 import { MetadataSchema } from '../libs/api';
 import { wallet } from '../libs/auth';
@@ -9,7 +10,8 @@ import dayjs from '../libs/dayjs';
 import logger from '../libs/logger';
 import { authenticate } from '../libs/security';
 import { formatToShortUrl } from '../libs/url';
-import { CheckoutSession } from '../store/models';
+import { getBlockletJson } from '../libs/util';
+import { CheckoutSession, Invoice, Subscription } from '../store/models';
 import { ProductVendor } from '../store/models/product-vendor';
 
 const authAdmin = authenticate<CheckoutSession>({ component: true, roles: ['owner', 'admin'] });
@@ -159,6 +161,8 @@ async function createVendor(req: any, res: any) {
       return res.status(400).json({ error: 'Vendor key already exists' });
     }
 
+    const blockletJson = await getBlockletJson(appUrl);
+
     const vendor = await ProductVendor.create({
       vendor_key: vendorKey,
       vendor_type: vendorType || 'launcher',
@@ -170,6 +174,10 @@ async function createVendor(req: any, res: any) {
       app_pid: appPid,
       app_logo: appLogo,
       metadata: metadata || {},
+      extends: {
+        appId: blockletJson?.appId,
+        appPk: blockletJson?.appPk,
+      },
       created_by: req.user?.did || 'admin',
     });
 
@@ -210,6 +218,8 @@ async function updateVendor(req: any, res: any) {
       app_logo: appLogo,
     } = value;
 
+    const blockletJson = await getBlockletJson(appUrl);
+
     if (req.body.vendorKey && req.body.vendorKey !== vendor.vendor_key) {
       const existingVendor = await ProductVendor.findOne({
         where: { vendor_key: req.body.vendorKey },
@@ -229,6 +239,10 @@ async function updateVendor(req: any, res: any) {
       app_pid: appPid,
       app_logo: appLogo,
       vendor_key: req.body.vendor_key,
+      extends: {
+        appId: blockletJson?.appId,
+        appPk: blockletJson?.appPk,
+      },
     };
 
     await vendor.update(Object.fromEntries(Object.entries(updates).filter(([, v]) => v !== undefined)));
@@ -362,9 +376,23 @@ async function getVendorStatus(sessionId: string, isDetail = false) {
     return getVendorStatusByVendorId(item.vendor_id, item.order_id, isDetail);
   });
 
+  const subscriptionId = doc.subscription_id;
+  let shortSubscriptionUrl = '';
+
+  if (isDetail && subscriptionId) {
+    const subscriptionUrl = getUrl(`/customer/subscription/${subscriptionId}`);
+
+    shortSubscriptionUrl = await formatToShortUrl({
+      url: subscriptionUrl,
+      maxVisits: 5,
+      validUntil: dayjs().add(20, 'minutes').format('YYYY-MM-DDTHH:mm:ss+00:00'),
+    });
+  }
+
   return {
     payment_status: doc.payment_status,
     session_status: doc.status,
+    subscriptionUrl: shortSubscriptionUrl,
     vendors: await Promise.all(vendors),
     error: null,
   };
@@ -443,12 +471,71 @@ async function redirectToVendor(req: any, res: any) {
   }
 }
 
+async function getVendorSubscription(req: any, res: any) {
+  const { sessionId } = req.params;
+
+  const checkoutSession = await CheckoutSession.findByPk(sessionId);
+
+  if (!checkoutSession) {
+    return res.status(404).json({ error: 'Checkout session not found' });
+  }
+
+  const subscription = await Subscription.findByPk(checkoutSession.subscription_id);
+
+  if (!subscription) {
+    return res.status(404).json({ error: 'Subscription not found' });
+  }
+
+  const invoices = await Invoice.findAll({
+    where: { subscription_id: subscription.id },
+    order: [['created_at', 'DESC']],
+    attributes: [
+      'id',
+      'amount_due',
+      'amount_paid',
+      'amount_remaining',
+      'status',
+      'currency_id',
+      'period_start',
+      'period_end',
+      'created_at',
+      'due_date',
+      'description',
+      'invoice_pdf',
+    ],
+    limit: 20,
+  });
+
+  return res.json({
+    subscription: subscription.toJSON(),
+    billing_history: invoices,
+  });
+}
+
+async function handleSubscriptionRedirect(req: any, res: any) {
+  const { sessionId } = req.params;
+
+  const checkoutSession = await CheckoutSession.findByPk(sessionId);
+  if (!checkoutSession) {
+    return res.status(404).json({ error: 'Checkout session not found' });
+  }
+
+  return res.redirect(getUrl(`/customer/subscription/${checkoutSession.subscription_id}`));
+}
+
 const router = Router();
 
+const ensureVendorAuth = middleware.ensureVendorAuth((vendorPk: string) =>
+  ProductVendor.findOne({ where: { 'extends.appPk': vendorPk } }).then((v) => v as any)
+);
+
 // FIXME: Authentication not yet added, awaiting implementation @Pengfei
 router.get('/order/:sessionId/status', validateParams(sessionIdParamSchema), getVendorFulfillmentStatus);
 router.get('/order/:sessionId/detail', validateParams(sessionIdParamSchema), getVendorFulfillmentDetail);
 
+router.get('/subscription/:sessionId/redirect', handleSubscriptionRedirect);
+router.get('/subscription/:sessionId', ensureVendorAuth, getVendorSubscription);
+
 router.get(
   '/open/:subscriptionId',
   authAdmin,

package/api/src/store/migrations/20250918-add-vendor-extends.ts

@@ -0,0 +1,20 @@
+import { safeApplyColumnChanges, type Migration } from '../migrate';
+
+export const up: Migration = async ({ context }) => {
+  // Add extends column to product_vendors table
+  await safeApplyColumnChanges(context, {
+    product_vendors: [
+      {
+        name: 'extends',
+        field: {
+          type: 'JSON',
+          allowNull: true,
+        },
+      },
+    ],
+  });
+};
+
+export const down: Migration = async ({ context }) => {
+  await context.removeColumn('product_vendors', 'extends');
+};

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

@@ -212,7 +212,9 @@ export class CheckoutSession extends Model<InferAttributes<CheckoutSession>, Inf
     | 'cancelled'
     | 'max_retries_exceeded'
     | 'return_requested'
-    | 'sent',
+    | 'sent'
+    | 'returning'
+    | 'returned',
     string
   >;
   declare vendor_info?: Array<{
@@ -227,7 +229,8 @@ export class CheckoutSession extends Model<InferAttributes<CheckoutSession>, Inf
       | 'cancelled'
       | 'max_retries_exceeded'
       | 'return_requested'
-      | 'sent';
+      | 'sent'
+      | 'returned';
     service_url?: string;
     app_url?: string;
     error_message?: string;

package/api/src/store/models/product-vendor.ts

@@ -19,6 +19,7 @@ export class ProductVendor extends Model<InferAttributes<ProductVendor>, InferCr
 
   declare status: 'active' | 'inactive';
   declare metadata: Record<string, any>;
+  declare extends: Record<string, any>;
 
   declare created_by: string;
   declare created_at: CreationOptional<Date>;
@@ -75,6 +76,11 @@ export class ProductVendor extends Model<InferAttributes<ProductVendor>, InferCr
       allowNull: true,
       defaultValue: {},
     },
+    extends: {
+      type: DataTypes.JSON,
+      allowNull: true,
+      defaultValue: {},
+    },
     created_by: {
       type: DataTypes.STRING(30),
       allowNull: true,

package/blocklet.yml

@@ -14,7 +14,7 @@ repository:
   type: git
   url: git+https://github.com/blocklet/payment-kit.git
 specVersion: 1.2.8
-version: 1.20.12
+version: 1.20.13
 logo: logo.png
 files:
   - dist

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "payment-kit",
-  "version": "1.20.12",
+  "version": "1.20.13",
   "scripts": {
     "dev": "blocklet dev --open",
     "lint": "tsc --noEmit && eslint src api/src --ext .mjs,.js,.jsx,.ts,.tsx",
@@ -56,8 +56,8 @@
     "@blocklet/error": "^0.2.5",
     "@blocklet/js-sdk": "^1.16.52-beta-20250912-112002-e3499e9c",
     "@blocklet/logger": "^1.16.52-beta-20250912-112002-e3499e9c",
-    "@blocklet/payment-react": "1.20.12",
-    "@blocklet/payment-vendor": "1.20.12",
+    "@blocklet/payment-react": "1.20.13",
+    "@blocklet/payment-vendor": "1.20.13",
     "@blocklet/sdk": "^1.16.52-beta-20250912-112002-e3499e9c",
     "@blocklet/ui-react": "^3.1.41",
     "@blocklet/uploader": "^0.2.11",
@@ -126,7 +126,7 @@
   "devDependencies": {
     "@abtnode/types": "^1.16.52-beta-20250912-112002-e3499e9c",
     "@arcblock/eslint-config-ts": "^0.3.3",
-    "@blocklet/payment-types": "1.20.12",
+    "@blocklet/payment-types": "1.20.13",
     "@types/cookie-parser": "^1.4.9",
     "@types/cors": "^2.8.19",
     "@types/debug": "^4.1.12",
@@ -173,5 +173,5 @@
       "parser": "typescript"
     }
   },
-  "gitHead": "e6c432f89c2bf305efc903c0809f4a0557c07774"
+  "gitHead": "0cbe918549f7d06561b5307fb947bfbbd2250984"
 }