payment-kit 1.15.17 → 1.15.18

package/api/src/queues/subscription.ts

@@ -1,5 +1,6 @@
 import type { LiteralUnion } from 'type-fest';
 
+import { createEvent } from '@api/libs/audit';
 import { ensurePassportRevoked } from '../integrations/blocklet/passport';
 import { batchHandleStripeSubscriptions } from '../integrations/stripe/resource';
 import { wallet } from '../libs/auth';
@@ -12,6 +13,7 @@ import createQueue from '../libs/queue';
 import { getStatementDescriptor } from '../libs/session';
 import {
   checkRemainingStake,
+  checkUsageReportEmpty,
   getSubscriptionCycleAmount,
   getSubscriptionCycleSetup,
   getSubscriptionStakeAddress,
@@ -111,6 +113,23 @@ const doHandleSubscriptionInvoice = async ({
     { product: true }
   );
 
+  const usageReportStart = usageStart || start - offset;
+  const usageReportEnd = usageEnd || end - offset;
+
+  // check if usage report is empty
+  const usageReportEmpty = await checkUsageReportEmpty(subscription, usageReportStart, usageReportEnd);
+  if (usageReportEmpty) {
+    createEvent('Subscription', 'usage.report.empty', subscription, {
+      usageReportStart,
+      usageReportEnd,
+    }).catch(console.error);
+    logger.info('create usage report empty event', {
+      subscriptionId: subscription.id,
+      usageReportStart,
+      usageReportEnd,
+    });
+  }
+
   // get usage summaries for this billing cycle
   expandedItems = await Promise.all(
     expandedItems.filter(filter).map(async (x: any) => {
@@ -119,8 +138,8 @@ const doHandleSubscriptionInvoice = async ({
       if (x.price.recurring?.usage_type === 'metered') {
         const rawQuantity = await UsageRecord.getSummary({
           id: x.id,
-          start: (usageStart || start) - offset,
-          end: (usageEnd || end) - offset,
+          start: usageReportStart,
+          end: usageReportEnd,
           method: x.price.recurring?.aggregate_usage,
           dryRun: false,
         });

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

@@ -136,6 +136,23 @@ export async function validateInventory(line_items: LineItem[], includePendingQu
   await Promise.all(checks);
 }
 
+const SubscriptionDataSchema = Joi.object({
+  service_actions: Joi.array()
+    .items(
+      Joi.object({
+        name: Joi.string().optional(),
+        color: Joi.string().allow('primary', 'secondary', 'success', 'error', 'warning').optional(),
+        variant: Joi.string().allow('text', 'contained', 'outlined').optional(),
+        text: Joi.object().required(),
+        link: Joi.string().uri().required(),
+        type: Joi.string().allow('notification', 'custom').optional(),
+        triggerEvents: Joi.array().items(Joi.string()).optional(),
+      })
+    )
+    .min(0)
+    .optional(),
+}).unknown(true);
+
 export const formatCheckoutSession = async (payload: any, throwOnEmptyItems = true) => {
   const raw: Partial<CheckoutSession> = Object.assign(
     {
@@ -161,6 +178,7 @@ export const formatCheckoutSession = async (payload: any, throwOnEmptyItems = tr
         billing_threshold_amount: 0,
         min_stake_amount: 0,
         trial_end: 0,
+        service_actions: [],
       },
       payment_intent_data: {},
       submit_type: 'pay',
@@ -193,6 +211,13 @@ export const formatCheckoutSession = async (payload: any, throwOnEmptyItems = tr
     raw.subscription_data.trial_period_days = Number(raw.subscription_data.trial_period_days);
   }
 
+  if (raw.subscription_data?.service_actions) {
+    const { error } = SubscriptionDataSchema.validate(raw.subscription_data);
+    if (error) {
+      throw new Error('Invalid service actions for checkout session');
+    }
+  }
+
   if (!raw.expires_at) {
     raw.expires_at = dayjs().unix() + CHECKOUT_SESSION_TTL;
   }
@@ -869,6 +894,7 @@ router.put('/:id/submit', user, ensureCheckoutSessionOpen, async (req, res) => {
             checkoutSession.subscription_data?.days_until_cancel ?? checkoutSession.metadata?.days_until_cancel,
           recovered_from: recoveredFrom?.id,
           metadata: omit(checkoutSession.metadata || {}, ['days_until_due', 'days_until_cancel']),
+          service_actions: checkoutSession.subscription_data?.service_actions || [],
         });
 
         logger.info('subscription created on checkout session submit', {

package/api/src/routes/subscriptions.ts

@@ -693,11 +693,13 @@ const updateSchema = Joi.object<{
   service_actions: Joi.array()
     .items(
       Joi.object({
-        name: Joi.string().required(),
-        color: Joi.string().allow('primary', 'secondary', 'success', 'error', 'warning').required(),
-        variant: Joi.string().allow('text', 'contained', 'outlined').required(),
+        name: Joi.string().optional(),
+        color: Joi.string().allow('primary', 'secondary', 'success', 'error', 'warning').optional(),
+        variant: Joi.string().allow('text', 'contained', 'outlined').optional(),
         text: Joi.object().required(),
         link: Joi.string().uri().required(),
+        type: Joi.string().allow('notification', 'custom').optional(),
+        triggerEvents: Joi.array().items(Joi.string()).optional(),
       })
     )
     .optional(),

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

@@ -24,6 +24,7 @@ import type {
   NftMintSettings,
   PaymentDetails,
   PaymentIntentData,
+  ServiceAction,
   SubscriptionData,
 } from './types';
 
@@ -158,6 +159,7 @@ export class CheckoutSession extends Model<InferAttributes<CheckoutSession>, Inf
 
   // When creating a subscription, the specified configuration data will be used.
   declare subscription_data?: SubscriptionData & {
+    service_actions?: ServiceAction[];
     billing_cycle_anchor?: number;
     metadata?: Record<string, any>;
     proration_behavior?: LiteralUnion<'create_prorations' | 'none', string>;

package/api/src/store/models/types.ts

@@ -44,10 +44,26 @@ export type PriceCurrency = {
   custom_unit_amount: CustomUnitAmount | null;
 };
 
+// 这里为triggerEvents的事件类型
+type NotificationActionEvents =
+  | 'customer.subscription.started'
+  | 'customer.subscription.renewed'
+  | 'customer.subscription.renew_failed'
+  | 'refund.succeeded'
+  | 'subscription.stake.slash.succeeded'
+  | 'customer.subscription.trial_will_end'
+  | 'customer.subscription.trial_start'
+  | 'customer.subscription.upgraded'
+  | 'customer.subscription.will_renew'
+  | 'customer.subscription.will_canceled'
+  | 'customer.subscription.deleted';
+
 export type ServiceAction = {
-  name: string;
-  color: string;
-  variant: string;
+  type?: LiteralUnion<'notification' | 'custom', string>;
+  triggerEvents?: NotificationActionEvents[];
+  name?: string;
+  color?: LiteralUnion<'primary' | 'secondary' | 'success' | 'error' | 'warning', string>;
+  variant?: LiteralUnion<'text' | 'contained' | 'outlined', string>;
   text: { [key: string]: string };
   link: string;
 };
@@ -640,7 +656,9 @@ export type EventType = LiteralUnion<
   | 'topup.succeeded'
   | 'transfer.created'
   | 'transfer.reversed'
-  | 'transfer.updated',
+  | 'transfer.updated'
+  | 'billing.discrepancy'
+  | 'usage.report.empty',
   string
 >;
 

package/api/src/store/models/usage-record.ts

@@ -100,17 +100,21 @@ export class UsageRecord extends Model<InferAttributes<UsageRecord>, InferCreati
     end,
     method,
     dryRun,
+    billed = false,
+    searchBilled = true,
   }: {
     id: string;
     start: number;
     end: number;
     method: LiteralUnion<'sum' | 'last_during_period' | 'max' | 'last_ever', string>;
     dryRun: boolean;
+    billed?: boolean;
+    searchBilled?: boolean;
   }): Promise<number> {
     const query = {
       where: {
         subscription_item_id: id,
-        billed: false,
+        ...(searchBilled ? { billed } : {}),
         timestamp: {
           [Op.gt]: start,
           [Op.lte]: end,

package/api/tests/libs/subscription.spec.ts

@@ -10,8 +10,9 @@ import {
   getSubscriptionTrialSetup,
   shouldCancelSubscription,
   getSubscriptionStakeAmountSetup,
+  checkUsageReportEmpty,
 } from '../../src/libs/subscription';
-import type { PaymentMethod, Subscription } from '../../src/store/models';
+import { PaymentMethod, Subscription, SubscriptionItem, UsageRecord, Price } from '../../src/store/models';
 
 describe('getDueUnit', () => {
   it('should return 60 for recurring interval of "hour"', () => {
@@ -508,3 +509,59 @@ describe('getSubscriptionStakeAmountSetup', () => {
     });
   });
 });
+
+// 模拟的依赖项
+const mockSubscriptionItems = [
+  { id: 'item_1', price_id: 'price_1', quantity: 1 },
+  { id: 'item_2', price_id: 'price_2', quantity: 1 },
+];
+
+const mockExpandedItems = [
+  { id: 'item_1', price: { recurring: { usage_type: 'metered' } } },
+  { id: 'item_2', price: { recurring: { usage_type: 'metered' } } },
+];
+
+const mockUsageRecordsEmpty: any[] = [];
+const mockUsageRecordsWithData = [{ id: 'usage_1' }];
+
+describe('checkUsageReportEmpty', () => {
+  const subscription = { id: 'sub_123' };
+  const usageReportStart = 1622505600;
+  const usageReportEnd = 1622592000;
+
+  beforeEach(() => {
+    // Reset any state if necessary
+  });
+
+  it('should return true if there are no usage records', async () => {
+    // Mock the behavior of the functions directly
+    jest.spyOn(SubscriptionItem, 'findAll').mockResolvedValue(mockSubscriptionItems as any);
+    jest.spyOn(Price, 'expand').mockResolvedValue(mockExpandedItems as any);
+    jest.spyOn(UsageRecord, 'findAll').mockResolvedValue(mockUsageRecordsEmpty);
+
+    const result = await checkUsageReportEmpty(subscription as any, usageReportStart, usageReportEnd);
+    expect(result).toBe(true);
+  });
+
+  it('should return false if there are usage records', async () => {
+    jest.spyOn(SubscriptionItem, 'findAll').mockResolvedValue(mockSubscriptionItems as any);
+    jest.spyOn(Price, 'expand').mockResolvedValue(mockExpandedItems as any);
+    jest.spyOn(UsageRecord, 'findAll').mockResolvedValue(mockUsageRecordsWithData as any);
+
+    const result = await checkUsageReportEmpty(subscription as any, usageReportStart, usageReportEnd);
+    expect(result).toBe(false);
+  });
+
+  it('should handle multiple metered items', async () => {
+    jest.spyOn(SubscriptionItem, 'findAll').mockResolvedValue(mockSubscriptionItems as any);
+    jest.spyOn(Price, 'expand').mockResolvedValue(mockExpandedItems as any);
+
+    jest
+      .spyOn(UsageRecord, 'findAll')
+      .mockResolvedValueOnce(mockUsageRecordsEmpty)
+      .mockResolvedValueOnce(mockUsageRecordsWithData as any);
+
+    const result = await checkUsageReportEmpty(subscription as any, usageReportStart, usageReportEnd);
+    expect(result).toBe(false);
+  });
+});

package/api/tests/libs/util.spec.ts

@@ -10,7 +10,9 @@ import {
   getDataObjectFromQuery,
   getNextRetry,
   tryWithTimeout,
+  getSubscriptionNotificationCustomActions,
 } from '../../src/libs/util';
+import type { Subscription } from '../../src/store/models';
 
 describe('createIdGenerator', () => {
   it('should return a function that generates an ID with the specified prefix and size', () => {
@@ -240,3 +242,136 @@ describe('formatAmountPrecisionLimit', () => {
     expect(result).toBe('');
   });
 });
+
+describe('getSubscriptionNotificationCustomActions', () => {
+  const mockSubscription: Partial<Subscription> = {
+    service_actions: [
+      {
+        type: 'notification',
+        triggerEvents: ['customer.subscription.started', 'customer.subscription.renewed'],
+        name: 'Action 1',
+        text: { en: 'Action 1 Text', zh: '操作1文本' },
+        link: 'https://example.com/action1',
+        color: 'blue',
+        variant: 'outlined',
+      },
+      {
+        type: 'notification',
+        triggerEvents: ['customer.subscription.renewed', 'customer.subscription.upgraded'],
+        name: 'Action 2',
+        text: { en: 'Action 2 Text', zh: '操作2文本' },
+        link: 'https://example.com/action2',
+        color: 'green',
+        variant: 'contained',
+      },
+      {
+        type: 'other',
+        triggerEvents: ['customer.subscription.started'],
+        name: 'Action 3',
+        text: { en: 'Action 3 Text', zh: '操作3文本' },
+        link: 'https://example.com/action3',
+        color: 'red',
+        variant: 'text',
+      },
+    ],
+  };
+
+  it('should return an empty array if subscription is null', () => {
+    const result = getSubscriptionNotificationCustomActions(null as any, 'customer.subscription.started', 'en');
+    expect(result).toEqual([]);
+  });
+
+  it('should return an empty array if service_actions is empty', () => {
+    const result = getSubscriptionNotificationCustomActions(
+      { service_actions: [] } as any,
+      'customer.subscription.started',
+      'en'
+    );
+    expect(result).toEqual([]);
+  });
+
+  it('should filter actions based on event type and return formatted actions with color and variant', () => {
+    const result = getSubscriptionNotificationCustomActions(
+      mockSubscription as any,
+      'customer.subscription.renewed',
+      'en'
+    );
+    expect(result).toEqual([
+      {
+        name: 'Action 1',
+        title: 'Action 1 Text',
+        link: 'https://example.com/action1',
+      },
+      {
+        name: 'Action 2',
+        title: 'Action 2 Text',
+        link: 'https://example.com/action2',
+      },
+    ]);
+  });
+
+  it('should return actions with correct locale, color, and variant', () => {
+    const result = getSubscriptionNotificationCustomActions(
+      mockSubscription as any,
+      'customer.subscription.renewed',
+      'zh'
+    );
+    expect(result).toEqual([
+      {
+        name: 'Action 1',
+        title: '操作1文本',
+        link: 'https://example.com/action1',
+      },
+      {
+        name: 'Action 2',
+        title: '操作2文本',
+        link: 'https://example.com/action2',
+      },
+    ]);
+  });
+
+  it('should not return actions of non-notification type', () => {
+    const result = getSubscriptionNotificationCustomActions(
+      mockSubscription as any,
+      'customer.subscription.started',
+      'en'
+    );
+    expect(result).toEqual([
+      {
+        name: 'Action 1',
+        title: 'Action 1 Text',
+        link: 'https://example.com/action1',
+      },
+    ]);
+  });
+
+  it('should return an empty array if no matching actions found', () => {
+    const result = getSubscriptionNotificationCustomActions(
+      mockSubscription as any,
+      'customer.subscription.deleted',
+      'en'
+    );
+    expect(result).toEqual([]);
+  });
+
+  it('should handle all valid NotificationActionEvents', () => {
+    const allEvents = [
+      'customer.subscription.started',
+      'customer.subscription.renewed',
+      'customer.subscription.renew_failed',
+      'refund.succeeded',
+      'subscription.stake.slash.succeeded',
+      'customer.subscription.trial_will_end',
+      'customer.subscription.trial_start',
+      'customer.subscription.upgraded',
+      'customer.subscription.will_renew',
+      'customer.subscription.will_canceled',
+      'customer.subscription.deleted',
+    ];
+
+    allEvents.forEach((event) => {
+      const result = getSubscriptionNotificationCustomActions(mockSubscription as any, event, 'en');
+      expect(Array.isArray(result)).toBeTruthy();
+    });
+  });
+});

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "payment-kit",
-  "version": "1.15.17",
+  "version": "1.15.18",
   "scripts": {
     "dev": "blocklet dev --open",
     "eject": "vite eject",
@@ -52,7 +52,7 @@
     "@arcblock/validator": "^1.18.135",
     "@blocklet/js-sdk": "^1.16.32",
     "@blocklet/logger": "^1.16.32",
-    "@blocklet/payment-react": "1.15.17",
+    "@blocklet/payment-react": "1.15.18",
     "@blocklet/sdk": "^1.16.32",
     "@blocklet/ui-react": "^2.10.45",
     "@blocklet/uploader": "^0.1.43",
@@ -118,7 +118,7 @@
   "devDependencies": {
     "@abtnode/types": "^1.16.32",
     "@arcblock/eslint-config-ts": "^0.3.2",
-    "@blocklet/payment-types": "1.15.17",
+    "@blocklet/payment-types": "1.15.18",
     "@types/cookie-parser": "^1.4.7",
     "@types/cors": "^2.8.17",
     "@types/debug": "^4.1.12",
@@ -160,5 +160,5 @@
       "parser": "typescript"
     }
   },
-  "gitHead": "746e67a4e0542f308289edd4e2d6bdd64e49e53e"
+  "gitHead": "f57a3e622d9701fa0421f1266efc2fd92bd84780"
 }

package/scripts/sdk.js

@@ -86,9 +86,43 @@ const payment = require('@blocklet/payment-js').default;
   //   cancel_url:
   //     'https://bbqa2t5pfyfroyobmzknmktshckzto4btkfagxyjqwy.did.abtnet.io/store/api/payment/cancel?redirect=https://bbqa2t5pfyfroyobmzknmktshckzto4btkfagxyjqwy.did.abtnet.io/maker/mint/z3CtLCSchoZj4H5gqwyATSAEdvfd1m88VnDUZ',
   //   mode: 'payment',
-  //   line_items: [{ price_id: 'price_wc1WPJy7FrbX1CBPJj7zuIys', quantity: 2 }],
-  //   metadata: { factoryAddress: 'z3CtLCSchoZj4H5gqwyATSAEdvfd1m88VnDUZ', quantity: 2 },
-  //   expires_at: 1721121607,
+  //   line_items: [
+  //     { price_id: 'price_G7TE6QZbvqkIaqzDJVb2afws', quantity: 2 },
+  //     { price_id: 'price_rOUdD9fQrBGqn6M3YywXdDeK', quantity: 2 },
+  //   ],
+  //   subscription_data: {
+  //     service_actions: [
+  //       {
+  //         type: 'notification',
+  //         text: {
+  //           zh: '查看文档',
+  //           en: 'View Documentation',
+  //         },
+  //         link: 'https://www.arcblock.io/docs/createblocklet/en/quick-start',
+  //         triggerEvents: ['customer.subscription.started', 'customer.subscription.deleted'],
+  //       },
+  //       {
+  //         type: 'notification',
+  //         text: {
+  //           zh: '社区提问',
+  //           en: 'Ask in Community',
+  //         },
+  //         link: 'https://community.arcblock.io/?locale=en',
+  //         triggerEvents: ['customer.subscription.started', 'customer.subscription.renewed'],
+  //       },
+  //       {
+  //         type: 'custom',
+  //         text: {
+  //           zh: '查看',
+  //           en: 'View',
+  //         },
+  //         link: 'https://www.arcblock.io/docs/createblocklet/en/quick-start',
+  //         color: 'primary',
+  //         variant: 'outlined',
+  //       },
+  //     ],
+  //   },
+  //   expires_at: 1729243800,
   // });
   // console.log('checkoutSession', checkoutSession);
   // const product = await payment.products.create({

package/src/components/invoice/list.tsx

@@ -229,7 +229,6 @@ export default function InvoiceList({
     columns.splice(3, 0, {
       label: t('common.customer'),
       name: 'customer_id',
-      width: 80,
       options: {
         customBodyRenderLite: (_: string, index: number) => {
           const item = data.list[index] as TInvoiceExpanded;

package/src/components/invoice/table.tsx

@@ -11,6 +11,7 @@ import { styled } from '@mui/system';
 import { isEmpty } from 'lodash';
 import LineItemActions from '../subscription/items/actions';
 import { UsageRecordDialog } from '../subscription/items/usage-records';
+import { getInvoiceUsageReportStartEnd } from '../../libs/util';
 
 type Props = {
   invoice: TInvoiceExpanded;
@@ -122,6 +123,8 @@ export default function InvoiceTable({ invoice, simple, emptyNodeText }: Props)
     subscriptionItemId: '',
   });
 
+  const usageReportRange = getInvoiceUsageReportStartEnd(invoice, true);
+
   const onOpenUsageRecords = (line: InvoiceDetailItem) => {
     if (line.rawQuantity && line.raw.subscription_id && line.raw.subscription_item_id) {
       setState({
@@ -271,8 +274,10 @@ export default function InvoiceTable({ invoice, simple, emptyNodeText }: Props)
           subscriptionId={state.subscriptionId}
           id={state.subscriptionItemId}
           onConfirm={onCloseUsageRecords}
-          start={invoice.metadata?.usage_start || invoice.period_start}
-          end={invoice.metadata?.usage_end || invoice.period_end}
+          start={usageReportRange.start}
+          end={usageReportRange.end}
+          title={t('admin.subscription.usage.title')}
+          disableAddUsageQuantity
         />
       )}
     </Root>

package/src/components/subscription/items/index.tsx

@@ -4,6 +4,7 @@ import { formatPrice, Table, TruncatedText, useMobile } from '@blocklet/payment-
 import type { TPaymentCurrency, TSubscriptionItemExpanded } from '@blocklet/payment-types';
 import { Avatar, Stack, Typography } from '@mui/material';
 
+import { Link } from 'react-router-dom';
 import Copyable from '../../copyable';
 import LineItemActions from './actions';
 import UsageRecords from './usage-records';
@@ -23,6 +24,8 @@ const size = { width: 48, height: 48 };
 export default function SubscriptionItemList({ data, currency, mode }: ListProps) {
   const { t } = useLocaleContext();
   const { isMobile } = useMobile();
+  const isAdmin = mode === 'admin';
+
   const columns = [
     {
       label: t('admin.subscription.product'),
@@ -53,13 +56,29 @@ export default function SubscriptionItemList({ data, currency, mode }: ListProps
                   {item.price.product.name.slice(0, 1)}
                 </Avatar>
               )}
-              <Typography color="text.primary" fontWeight={600}>
-                <TruncatedText text={item?.price.product.name} maxLength={isMobile ? 20 : 50} useWidth />
-                {mode === 'customer' ? '' : ` - ${item?.price_id}`}
-              </Typography>
-              <Typography color="text.secondary" whiteSpace="nowrap">
-                {formatPrice(item.price, currency, item?.price.product.unit_label)}
-              </Typography>
+              {isAdmin ? (
+                <>
+                  <Typography color="text.primary" fontWeight={600}>
+                    <Link to={`/admin/products/${item?.price.product_id}`}>
+                      <TruncatedText text={item?.price.product.name} maxLength={isMobile ? 20 : 50} useWidth />
+                    </Link>
+                  </Typography>
+                  <Typography color="text.secondary" whiteSpace="nowrap">
+                    <Link to={`/admin/products/${item?.price.id}`}>
+                      {formatPrice(item.price, currency, item?.price.product.unit_label)}
+                    </Link>
+                  </Typography>
+                </>
+              ) : (
+                <>
+                  <Typography color="text.primary" fontWeight={600}>
+                    <TruncatedText text={item?.price.product.name} maxLength={isMobile ? 20 : 50} useWidth />
+                  </Typography>
+                  <Typography color="text.secondary" whiteSpace="nowrap">
+                    {formatPrice(item.price, currency, item?.price.product.unit_label)}
+                  </Typography>
+                </>
+              )}
             </Stack>
           );
         },