payment-kit 1.20.22 → 1.21.0

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

@@ -234,23 +234,25 @@ export class SubscriptionRenewFailedEmailTemplate
                 text: productName,
               },
             },
-            ...(payer && [
-              {
-                type: 'text',
-                data: {
-                  type: 'plain',
-                  color: '#9397A1',
-                  text: translate('notification.common.payer', locale),
-                },
-              },
-              {
-                type: 'text',
-                data: {
-                  type: 'plain',
-                  text: payer,
-                },
-              },
-            ]),
+            ...(payer
+              ? [
+                  {
+                    type: 'text',
+                    data: {
+                      type: 'plain',
+                      color: '#9397A1',
+                      text: translate('notification.common.payer', locale),
+                    },
+                  },
+                  {
+                    type: 'text',
+                    data: {
+                      type: 'plain',
+                      text: payer,
+                    },
+                  },
+                ]
+              : []),
             {
               type: 'text',
               data: {

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

@@ -390,23 +390,25 @@ export class SubscriptionWillRenewEmailTemplate extends BaseSubscriptionEmailTem
           type: 'section',
           fields: [
             ...commonFields,
-            ...(payer && [
-              {
-                type: 'text',
-                data: {
-                  type: 'plain',
-                  color: '#9397A1',
-                  text: translate('notification.common.payer', locale),
-                },
-              },
-              {
-                type: 'text',
-                data: {
-                  type: 'plain',
-                  text: payer,
-                },
-              },
-            ]),
+            ...(payer
+              ? [
+                  {
+                    type: 'text',
+                    data: {
+                      type: 'plain',
+                      color: '#9397A1',
+                      text: translate('notification.common.payer', locale),
+                    },
+                  },
+                  {
+                    type: 'text',
+                    data: {
+                      type: 'plain',
+                      text: payer,
+                    },
+                  },
+                ]
+              : []),
             ...renewAmountFields,
             ...balanceFields,
             ...insufficientBalanceFields,

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

@@ -17,10 +17,11 @@ import {
 } from './types';
 import { formatVendorUrl } from './util';
 
-const doRequestVendorData = (vendor: ProductVendor, orderId: string, url: string) => {
+const doRequestVendorData = (vendor: ProductVendor, orderId: string, url: string, options: { shortUrl: boolean }) => {
   const { headers } = VendorAuth.signRequestWithHeaders({});
   const name = vendor?.name;
   const key = vendor?.vendor_key;
+  const { shortUrl } = options;
 
   return fetch(url, { headers })
     .then(async (r) => {
@@ -38,7 +39,7 @@ const doRequestVendorData = (vendor: ProductVendor, orderId: string, url: string
           `vendor status fetch failed, vendor: ${vendor.vendor_key}, orderId: ${orderId}, status: ${r.status}, url: ${url}`
         );
       }
-      if (!data.dashboardUrl) {
+      if (!shortUrl || !data.dashboardUrl) {
         return {
           ...data,
           name,
@@ -255,15 +256,15 @@ export class LauncherAdapter implements VendorAdapter {
     }
   }
 
-  getOrderStatus(vendor: ProductVendor, orderId: string): Promise<any> {
+  getOrderStatus(vendor: ProductVendor, orderId: string, options: { shortUrl: boolean }): Promise<any> {
     const url = formatVendorUrl(vendor, `/api/vendor/status/${orderId}`);
 
-    return doRequestVendorData(vendor, orderId, url);
+    return doRequestVendorData(vendor, orderId, url, options);
   }
 
-  getOrder(vendor: ProductVendor, orderId: string): Promise<any> {
+  getOrder(vendor: ProductVendor, orderId: string, options: { shortUrl: boolean }): Promise<any> {
     const url = formatVendorUrl(vendor, `/api/vendor/orders/${orderId}`);
 
-    return doRequestVendorData(vendor, orderId, url);
+    return doRequestVendorData(vendor, orderId, url, options);
   }
 }

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

@@ -87,6 +87,6 @@ export interface VendorAdapter {
   fulfillOrder(params: FulfillOrderParams): Promise<FulfillOrderResult>;
   requestReturn(params: ReturnRequestParams): Promise<ReturnRequestResult>;
   checkOrderStatus(params: CheckOrderStatusParams): Promise<CheckOrderStatusResult>;
-  getOrder(vendor: ProductVendor, orderId: string): Promise<any>;
-  getOrderStatus(vendor: ProductVendor, orderId: string): Promise<any>;
+  getOrder(vendor: ProductVendor, orderId: string, option?: Record<string, any>): Promise<any>;
+  getOrderStatus(vendor: ProductVendor, orderId: string, option?: Record<string, any>): Promise<any>;
 }

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

@@ -158,7 +158,7 @@ export class VendorFulfillmentService {
             destination,
             amount: result.commissionAmount,
             currency_id: checkoutSession.currency_id,
-            customer_id: checkoutSession.customer_id || '',
+            customer_id: '',
             payment_intent_id: paymentIntentId,
             payment_method_id: paymentMethodId,
             status: paymentMethod?.type === 'stripe' ? 'deferred' : 'pending',

package/api/src/routes/vendor.ts

@@ -316,7 +316,12 @@ async function testVendorConnection(req: any, res: any) {
   }
 }
 
-async function executeVendorOperation(vendorId: string, orderId: string, operation: 'getOrder' | 'getOrderStatus') {
+async function executeVendorOperation(
+  vendorId: string,
+  orderId: string,
+  operation: 'getOrder' | 'getOrderStatus',
+  shortUrl: boolean
+) {
   if (!vendorId || !orderId) {
     return {
       error: 'Bad Request',
@@ -336,7 +341,7 @@ async function executeVendorOperation(vendorId: string, orderId: string, operati
 
   try {
     const vendorAdapter = await VendorFulfillmentService.getVendorAdapter(vendor.vendor_key);
-    const data = await vendorAdapter[operation](vendor, orderId);
+    const data = await vendorAdapter[operation](vendor, orderId, { shortUrl });
 
     return { data: { ...data, vendorType: vendor.vendor_type }, code: 200 };
   } catch (error: any) {
@@ -355,7 +360,7 @@ async function executeVendorOperation(vendorId: string, orderId: string, operati
   }
 }
 
-async function processVendorOrders(sessionId: string, operation: 'getOrder' | 'getOrderStatus') {
+async function processVendorOrders(sessionId: string, operation: 'getOrder' | 'getOrderStatus', shortUrl: boolean) {
   const doc = await CheckoutSession.findByPk(sessionId);
 
   if (!doc) {
@@ -397,7 +402,7 @@ async function processVendorOrders(sessionId: string, operation: 'getOrder' | 'g
       };
     }
 
-    const result = await executeVendorOperation(item.vendor_id, item.order_id, operation);
+    const result = await executeVendorOperation(item.vendor_id, item.order_id, operation, shortUrl);
 
     // Handle error responses from vendor functions
     if (result.error) {
@@ -431,7 +436,7 @@ async function processVendorOrders(sessionId: string, operation: 'getOrder' | 'g
 }
 
 async function getVendorStatus(sessionId: string) {
-  const result: any = await processVendorOrders(sessionId, 'getOrderStatus');
+  const result: any = await processVendorOrders(sessionId, 'getOrderStatus', false);
 
   if (result.subscriptionId) {
     const subscriptionUrl = getUrl(`/customer/subscription/${result.subscriptionId}`);
@@ -463,9 +468,10 @@ async function getVendorFulfillmentStatus(req: any, res: any) {
 
 async function getVendorFulfillmentDetail(req: any, res: any) {
   const { sessionId } = req.params;
+  const { shortUrl } = req.query;
 
   try {
-    const detail = await processVendorOrders(sessionId, 'getOrder');
+    const detail = await processVendorOrders(sessionId, 'getOrder', shortUrl === 'true');
     if (detail.code) {
       return res.status(detail.code).json({ error: detail.error });
     }
@@ -505,7 +511,7 @@ async function redirectToVendor(req: any, res: any) {
       return res.redirect('/404');
     }
 
-    const result = await executeVendorOperation(vendorId, order.order_id || '', 'getOrder');
+    const result = await executeVendorOperation(vendorId, order.order_id || '', 'getOrder', false);
     if (result.error || !result.data) {
       logger.warn('Vendor status detail not found', {
         subscriptionId,

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.22
+version: 1.21.0
 logo: logo.png
 files:
   - dist

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "payment-kit",
-  "version": "1.20.22",
+  "version": "1.21.0",
   "scripts": {
     "dev": "blocklet dev --open",
     "lint": "tsc --noEmit && eslint src api/src --ext .mjs,.js,.jsx,.ts,.tsx",
@@ -45,33 +45,33 @@
   },
   "dependencies": {
     "@abtnode/cron": "^1.16.52-beta-20250912-112002-e3499e9c",
-    "@arcblock/did": "^1.25.3",
-    "@arcblock/did-connect-react": "^3.1.41",
+    "@arcblock/did": "^1.25.4",
+    "@arcblock/did-connect-react": "^3.1.43",
     "@arcblock/did-connect-storage-nedb": "^1.8.0",
-    "@arcblock/did-util": "^1.25.3",
-    "@arcblock/jwt": "^1.25.3",
-    "@arcblock/ux": "^3.1.41",
-    "@arcblock/validator": "^1.25.3",
+    "@arcblock/did-util": "^1.25.4",
+    "@arcblock/jwt": "^1.25.4",
+    "@arcblock/ux": "^3.1.43",
+    "@arcblock/validator": "^1.25.4",
     "@blocklet/did-space-js": "^1.1.27",
     "@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-broker-client": "1.20.22",
-    "@blocklet/payment-react": "1.20.22",
-    "@blocklet/payment-vendor": "1.20.22",
+    "@blocklet/payment-broker-client": "1.21.0",
+    "@blocklet/payment-react": "1.21.0",
+    "@blocklet/payment-vendor": "1.21.0",
     "@blocklet/sdk": "^1.16.52-beta-20250912-112002-e3499e9c",
-    "@blocklet/ui-react": "^3.1.41",
+    "@blocklet/ui-react": "^3.1.43",
     "@blocklet/uploader": "^0.2.12",
-    "@blocklet/xss": "^0.2.7",
+    "@blocklet/xss": "^0.2.8",
     "@mui/icons-material": "^7.1.2",
     "@mui/lab": "7.0.0-beta.14",
     "@mui/material": "^7.1.2",
     "@mui/system": "^7.1.1",
-    "@ocap/asset": "^1.25.3",
-    "@ocap/client": "^1.25.3",
-    "@ocap/mcrypto": "^1.25.3",
-    "@ocap/util": "^1.25.3",
-    "@ocap/wallet": "^1.25.3",
+    "@ocap/asset": "^1.25.4",
+    "@ocap/client": "^1.25.4",
+    "@ocap/mcrypto": "^1.25.4",
+    "@ocap/util": "^1.25.4",
+    "@ocap/wallet": "^1.25.4",
     "@stripe/react-stripe-js": "^2.9.0",
     "@stripe/stripe-js": "^2.4.0",
     "ahooks": "^3.8.5",
@@ -128,7 +128,7 @@
   "devDependencies": {
     "@abtnode/types": "^1.16.52-beta-20250912-112002-e3499e9c",
     "@arcblock/eslint-config-ts": "^0.3.3",
-    "@blocklet/payment-types": "1.20.22",
+    "@blocklet/payment-types": "1.21.0",
     "@types/cookie-parser": "^1.4.9",
     "@types/cors": "^2.8.19",
     "@types/debug": "^4.1.12",
@@ -175,5 +175,5 @@
       "parser": "typescript"
     }
   },
-  "gitHead": "a0a691de0cd6e47efbc0e4de01d200bb9193c435"
+  "gitHead": "d133aa0e8c6681dd77bafe024c1e1dafb1addf0d"
 }

package/src/locales/en.tsx

@@ -94,6 +94,7 @@ export default flat({
     promotional: 'Promotional',
     viewInvoice: 'View Invoice',
     viewSourceData: 'View Source',
+    goToConfigure: 'Go to Configure',
   },
   notification: {
     preferences: {
@@ -1685,6 +1686,41 @@ export default flat({
         title: 'Pricing Tables',
         intro: 'Create beautiful pricing tables for your products',
       },
+      metering: {
+        title: 'Usage Metering',
+        intro: 'Track usage with meters and sell credits as top-up packages',
+        dialog: {
+          title: 'How to set up credit-based metering',
+          description:
+            'Credit-based metering allows you to track usage and charge customers based on consumption. Follow these steps to get started:',
+          steps: {
+            step1: {
+              title: 'Create a meter to track your usage events',
+              description:
+                'Set up meters to monitor API calls, data usage, or any measurable activity in your application.',
+            },
+            step2: {
+              title: 'Create Credit top-up products and pricing',
+              description:
+                'Define credit packages that customers can purchase, with flexible pricing models and validity periods.',
+            },
+            step3: {
+              title: 'Create a payment link and share it so users can buy Credits',
+              description: 'Generate shareable payment links that allow customers to easily purchase credit packages.',
+            },
+            step4: {
+              title: 'Integrate and report Credit usage',
+              description:
+                'Use our SDK to report usage events and automatically deduct credits from customer balances.',
+            },
+          },
+          docText: 'Read the credit billing guide',
+        },
+      },
+      promotions: {
+        title: 'Promotions',
+        intro: 'Create coupons and promotion codes to drive conversions',
+      },
       donate: {
         title: 'Donation',
         intro: 'Add donation button to your application with <CheckoutDonate />',
@@ -1699,5 +1735,6 @@ export default flat({
         link: 'https://www.npmjs.com/package/@blocklet/payment-js',
       },
     },
+    viewDocs: 'View docs',
   },
 });

package/src/locales/zh.tsx

@@ -93,6 +93,7 @@ export default flat({
     promotional: '促销',
     viewInvoice: '查看账单',
     viewSourceData: '查看来源',
+    goToConfigure: '前往配置',
   },
   notification: {
     preferences: {
@@ -1632,6 +1633,37 @@ export default flat({
         title: '定价表',
         intro: '为您的产品创建美观的定价表',
       },
+      metering: {
+        title: '计量与额度',
+        intro: '使用计量器跟踪用量，并通过额度套餐售卖 Credits',
+        dialog: {
+          title: '如何开启 Credit 计费',
+          description: 'Credit 计费模式让您可以跟踪用量并基于消费向客户收费。按照以下步骤开始配置：',
+          steps: {
+            step1: {
+              title: '创建计量器用于跟踪用量事件',
+              description: '设置计量器来监控 API 调用、数据使用量或应用中任何可测量的活动。',
+            },
+            step2: {
+              title: '创建 Credits 购买套餐和定价',
+              description: '定义客户可以购买的额度套餐，支持灵活的定价模式和有效期设置。',
+            },
+            step3: {
+              title: '创建支付链接并分享给用户',
+              description: '生成可分享的支付链接，让客户轻松购买额度套餐。',
+            },
+            step4: {
+              title: '集成并上报 Credits 用量',
+              description: '使用我们的 SDK 上报使用事件，自动从客户余额中扣除额度。',
+            },
+          },
+          docText: '查看 Credit 计费指南',
+        },
+      },
+      promotions: {
+        title: '促销与优惠',
+        intro: '创建优惠券与促销码，提升转化率',
+      },
       donate: {
         title: '打赏功能',
         intro: '使用 <CheckoutDonate /> 组件为应用添加打赏按钮',
@@ -1646,5 +1678,6 @@ export default flat({
         link: 'https://www.npmjs.com/package/@blocklet/payment-js',
       },
     },
+    viewDocs: '查看文档',
   },
 });

package/src/pages/integrations/overview.tsx

@@ -1,5 +1,6 @@
 import { useLocaleContext } from '@arcblock/ux/lib/Locale/context';
-import { Box, Grid, Typography, Divider } from '@mui/material';
+import { Box, Grid, Typography, Divider, Button, Link, Tooltip } from '@mui/material';
+import Dialog from '@arcblock/ux/lib/Dialog';
 import { useNavigate } from 'react-router-dom';
 import {
   Link as LinkIcon,
@@ -8,7 +9,11 @@ import {
   Inventory2Outlined,
   TableChartOutlined,
   FavoriteBorderOutlined,
+  Speed,
+  LocalOfferOutlined,
+  HelpOutline,
 } from '@mui/icons-material';
+import { useState } from 'react';
 
 const basicFeatures = [
   {
@@ -32,6 +37,24 @@ const basicFeatures = [
 ];
 
 const advancedFeatures = [
+  {
+    title: 'integrations.features.metering.title',
+    description: 'integrations.features.metering.intro',
+    icon: <Speed sx={{ fontSize: 32, color: 'text.lighter' }} />,
+    dialog: 'metering',
+    doc: {
+      url: 'https://www.arcblock.io/blog/en/payment-kit-enhanced-credit-management',
+    },
+  },
+  {
+    title: 'integrations.features.promotions.title',
+    description: 'integrations.features.promotions.intro',
+    icon: <LocalOfferOutlined sx={{ fontSize: 32, color: 'text.lighter' }} />,
+    path: '/admin/products/coupons',
+    doc: {
+      url: 'https://www.arcblock.io/content/blog/en/payment-kit-promotion-support',
+    },
+  },
   {
     title: 'integrations.features.donate.title',
     description: 'integrations.features.donate.intro',
@@ -48,7 +71,7 @@ const advancedFeatures = [
     title: 'integrations.features.api.title',
     description: 'integrations.features.api.intro',
     icon: <Code sx={{ fontSize: 32, color: 'text.lighter' }} />,
-    path: 'https://www.arcblock.io/docs/arcblock-payment-kit/en/start-payment-js',
+    path: 'https://www.staging.arcblock.io/content/docs/payment-kit-sdk',
     external: true,
   },
 ];
@@ -56,8 +79,13 @@ const advancedFeatures = [
 export default function Overview() {
   const { t } = useLocaleContext();
   const navigate = useNavigate();
+  const [openMeterDialog, setOpenMeterDialog] = useState(false);
 
   const handleClick = (item: any) => {
+    if (item.dialog === 'metering') {
+      setOpenMeterDialog(true);
+      return;
+    }
     if (item.external) {
       window.open(item.path, '_blank');
     } else {
@@ -179,13 +207,37 @@ export default function Overview() {
                   mb: 1,
                 }}>
                 {item.icon}
-                <Typography
-                  variant="h4"
+                <Box
                   sx={{
+                    display: 'flex',
+                    alignItems: 'center',
                     mt: 1.5,
                   }}>
-                  {t(item.title)}
-                </Typography>
+                  <Typography variant="h4">{t(item.title)}</Typography>
+                  {item.doc?.url && (
+                    <Tooltip title={t('integrations.viewDocs')} placement="top">
+                      <Link
+                        href={item.doc.url}
+                        target="_blank"
+                        rel="noopener"
+                        onClick={(e) => e.stopPropagation()}
+                        sx={{
+                          display: 'flex',
+                          alignItems: 'center',
+                          ml: 1,
+                          color: 'text.secondary',
+                          '&:hover': { color: 'primary.main' },
+                        }}>
+                        <HelpOutline
+                          fontSize="small"
+                          sx={{
+                            cursor: 'pointer',
+                          }}
+                        />
+                      </Link>
+                    </Tooltip>
+                  )}
+                </Box>
               </Box>
               <Typography
                 variant="body2"
@@ -198,6 +250,96 @@ export default function Overview() {
           </Grid>
         ))}
       </Grid>
+
+      <Dialog
+        open={openMeterDialog}
+        onClose={() => setOpenMeterDialog(false)}
+        maxWidth="sm"
+        fullWidth
+        className="base-dialog"
+        title={t('integrations.features.metering.dialog.title')}
+        actions={
+          <Box sx={{ display: 'flex', gap: 2 }}>
+            <Button onClick={() => setOpenMeterDialog(false)}>{t('common.cancel')}</Button>
+            <Button onClick={() => navigate('/admin/meters')} variant="contained">
+              {t('common.goToConfigure')}
+            </Button>
+          </Box>
+        }>
+        <Typography variant="body2" sx={{ color: 'text.secondary', mb: 3 }}>
+          {t('integrations.features.metering.dialog.description')}
+        </Typography>
+
+        <Box
+          component="ol"
+          sx={{
+            pl: 0,
+            mb: 3,
+            listStyle: 'none',
+            counterReset: 'step-counter',
+          }}>
+          {['step1', 'step2', 'step3', 'step4'].map((stepKey) => (
+            <Box
+              key={stepKey}
+              component="li"
+              sx={{
+                mb: 3,
+                pl: 3,
+                position: 'relative',
+                counterIncrement: 'step-counter',
+                '&::before': {
+                  content: 'counter(step-counter)',
+                  position: 'absolute',
+                  left: 0,
+                  top: 0,
+                  width: 24,
+                  height: 24,
+                  borderRadius: '50%',
+                  backgroundColor: 'primary.main',
+                  color: 'white',
+                  fontSize: '12px',
+                  fontWeight: 'bold',
+                  display: 'flex',
+                  alignItems: 'center',
+                  justifyContent: 'center',
+                },
+              }}>
+              <Box sx={{ ml: 0.5 }}>
+                <Typography variant="subtitle2" sx={{ fontWeight: 600, mb: 0.5 }}>
+                  {t(`integrations.features.metering.dialog.steps.${stepKey}.title`)}
+                </Typography>
+                <Typography variant="body2" sx={{ color: 'text.secondary', lineHeight: 1.5 }}>
+                  {t(`integrations.features.metering.dialog.steps.${stepKey}.description`)}
+                </Typography>
+              </Box>
+            </Box>
+          ))}
+        </Box>
+
+        <Box
+          sx={{
+            p: 2,
+            backgroundColor: 'action.hover',
+            borderRadius: 1,
+            border: '1px solid',
+            borderColor: 'divider',
+          }}>
+          <Link
+            href="https://www.staging.arcblock.io/content/docs/payment-kit-sdk/en/payment-kit-sdk-core-concepts-credit-billing"
+            target="_blank"
+            rel="noopener"
+            underline="hover"
+            sx={{
+              color: 'primary.main',
+              fontWeight: 500,
+              display: 'flex',
+              alignItems: 'center',
+              gap: 0.5,
+            }}>
+            {t('integrations.features.metering.dialog.docText')}
+          </Link>
+        </Box>
+      </Dialog>
     </Box>
   );
 }