payment-kit 1.19.0 → 1.19.2

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

@@ -20,6 +20,7 @@ import { createIdGenerator, formatMetadata } from '../../libs/util';
 import { sequelize } from '../sequelize';
 import type { TPaymentCurrency } from './payment-currency';
 import type { CustomUnitAmount, LineItem, PriceCurrency, PriceRecurring, PriceTier, TransformQuantity } from './types';
+import { Meter, type TMeter } from './meter';
 
 export const nextPriceId = createIdGenerator('price', 24);
 
@@ -32,6 +33,7 @@ type TPriceExpanded = TPrice & {
     upsells_to: TPriceExpanded;
     upsells_to_id: string;
   };
+  meter?: TMeter;
 };
 type TLineItemExpanded = LineItem & { price: TPriceExpanded; upsell_price: TPriceExpanded };
 
@@ -395,6 +397,10 @@ export class Price extends Model<InferAttributes<Price>, InferCreationAttributes
               x.upsell.upsells_to = to;
             }
           }
+          if (x.recurring?.meter_id) {
+            // @ts-ignore
+            x.meter = await Meter.findByPk(x.recurring?.meter_id);
+          }
         })
       );
     }

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

@@ -20,7 +20,7 @@ export class Product extends Model<InferAttributes<Product>, InferCreationAttrib
   declare livemode: boolean;
   declare locked: CreationOptional<boolean>;
 
-  declare type: LiteralUnion<'service' | 'good', string>;
+  declare type: LiteralUnion<'service' | 'good' | 'credit', string>;
 
   // The product’s name, meant to be displayable to the customer.
   declare name: string;
@@ -79,7 +79,7 @@ export class Product extends Model<InferAttributes<Product>, InferCreationAttrib
       defaultValue: false,
     },
     type: {
-      type: DataTypes.ENUM('service', 'good'),
+      type: DataTypes.ENUM('service', 'good', 'credit'),
     },
     name: {
       type: DataTypes.STRING(512),

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

@@ -410,6 +410,30 @@ export class Subscription extends Model<InferAttributes<Subscription>, InferCrea
     return this.isActive() && (!!this.cancel_at_period_end || !!this.cancel_at);
   }
 
+  public async isConsumesCredit(): Promise<boolean> {
+    // @ts-ignore
+    const { SubscriptionItem, Price } = this.sequelize.models;
+    if (!SubscriptionItem || !Price) {
+      return false;
+    }
+
+    // 查询订阅的所有价格项
+    const items = await SubscriptionItem.findAll({
+      where: { subscription_id: this.id },
+      include: [
+        {
+          model: Price,
+          as: 'price',
+        },
+      ],
+    });
+
+    return items.some((item: any) => {
+      const recurring = item.price?.recurring;
+      return recurring && recurring.usage_type === 'metered' && recurring.meter_id;
+    });
+  }
+
   public async start() {
     if (this.status === 'active') {
       logger.warn(`subscription already active: ${this.id}`);

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

@@ -46,6 +46,7 @@ export type PriceRecurring = {
   interval_count: number;
   aggregate_usage?: LiteralUnion<'sum' | 'last_during_period' | 'max' | 'last_ever', string>;
   usage_type?: LiteralUnion<'licensed' | 'metered', string>;
+  meter_id?: string;
 };
 
 export type PriceCurrency = {
@@ -325,7 +326,7 @@ export type PaymentDetails = {
   arcblock?: {
     tx_hash: string;
     payer: string;
-    type?: LiteralUnion<'slash' | 'transfer' | 'delegate' | 'stake_return', string>;
+    type?: LiteralUnion<'slash' | 'transfer' | 'delegate' | 'stake_return' | 'credit', string>;
     receiver?: string;
     staking?: {
       tx_hash: string;
@@ -722,7 +723,11 @@ export type EventType = LiteralUnion<
   | 'transfer.reversed'
   | 'transfer.updated'
   | 'billing.discrepancy'
-  | 'usage.report.empty',
+  | 'usage.report.empty'
+  | 'customer.credit.insufficient'
+  | 'customer.credit_grant.granted'
+  | 'customer.credit_grant.low_balance'
+  | 'customer.credit_grant.depleted',
   string
 >;
 
@@ -751,3 +756,24 @@ export type NotificationSetting = {
   exclude_events?: EventType[];
   include_events?: EventType[];
 };
+
+export type CreditGrantApplicabilityConfig = {
+  scope: {
+    prices?: string[]; // 可选，指定适用的价格ID列表
+    price_type?: 'metered'; // 可选，按价格类型适用, 目前只支持metered
+  };
+};
+
+export type MeterEventStatus =
+  | 'pending'
+  | 'processing'
+  | 'requires_action'
+  | 'requires_capture'
+  | 'completed'
+  | 'canceled';
+
+export type MeterEventPayload = {
+  customer_id: string;
+  value: string;
+  subscription_id?: string;
+};

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

@@ -11,6 +11,7 @@ import {
   getSubscriptionStakeAmountSetup,
   checkUsageReportEmpty,
   calculateRecommendedRechargeAmount,
+  getSubscriptionCycleSetup,
 } from '../../src/libs/subscription';
 import { PaymentMethod, Subscription, SubscriptionItem, UsageRecord, Price } from '../../src/store/models';
 
@@ -766,3 +767,55 @@ describe('calculateRecommendedRechargeAmount', () => {
     expect(result.amount).toBe('300');
   });
 });
+
+describe('getSubscriptionCycleSetup', () => {
+  const mockRecurring = {
+    interval: 'day',
+    interval_count: 1,
+    usage_type: 'licensed',
+  } as any;
+
+  it('should return normal setup without catchUp option', () => {
+    const previousPeriodEnd = dayjs().subtract(1, 'day').unix();
+    const result = getSubscriptionCycleSetup(mockRecurring, previousPeriodEnd);
+
+    expect(result.missedPeriods).toBe(0);
+    expect(result.period.start).toBe(previousPeriodEnd);
+    expect(result.recovery).toBeUndefined();
+  });
+
+  it('should detect and calculate missed periods with catchUp enabled', () => {
+    const previousPeriodEnd = dayjs().subtract(5, 'days').unix(); // 5 days ago
+    const result = getSubscriptionCycleSetup(mockRecurring, previousPeriodEnd, {
+      catchUp: true,
+      maxMissedPeriods: 10,
+    });
+
+    expect(result.missedPeriods).toBeGreaterThan(0);
+    expect(result.recovery).toBeDefined();
+    expect(result.recovery?.originalPeriodEnd).toBe(previousPeriodEnd);
+    expect(result.recovery?.periodsSkipped).toBeGreaterThan(0);
+    expect(result.period.start).toBeGreaterThan(previousPeriodEnd);
+  });
+
+  it('should limit missed periods to maxMissedPeriods', () => {
+    const previousPeriodEnd = dayjs().subtract(100, 'days').unix(); // Very old
+    const result = getSubscriptionCycleSetup(mockRecurring, previousPeriodEnd, {
+      catchUp: true,
+      maxMissedPeriods: 10,
+    });
+
+    expect(result.missedPeriods).toBe(10);
+    expect(result.recovery?.wasLimited).toBe(true);
+  });
+
+  it('should handle future period end without catchUp', () => {
+    const futurePeriodEnd = dayjs().add(1, 'day').unix();
+    const result = getSubscriptionCycleSetup(mockRecurring, futurePeriodEnd, {
+      catchUp: true,
+    });
+
+    expect(result.missedPeriods).toBe(0);
+    expect(result.period.start).toBe(futurePeriodEnd);
+  });
+});

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.19.0
+version: 1.19.2
 logo: logo.png
 files:
   - dist
@@ -169,3 +169,11 @@ events:
     description: Refund has been successfully processed and completed
   - type: manual.notification
     description: Application will send notification to user manually
+  - type: customer.credit_grant.granted
+    description: Credit grant has been successfully granted
+  - type: customer.credit_grant.low_balance
+    description: Credit grant has low balance
+  - type: customer.credit_grant.depleted
+    description: Credit grant has been depleted
+  - type: customer.credit.insufficient
+    description: Customer has insufficient credit

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "payment-kit",
-  "version": "1.19.0",
+  "version": "1.19.2",
   "scripts": {
     "dev": "blocklet dev --open",
     "lint": "tsc --noEmit && eslint src api/src --ext .mjs,.js,.jsx,.ts,.tsx",
@@ -54,7 +54,7 @@
     "@blocklet/did-space-js": "^1.0.62",
     "@blocklet/js-sdk": "^1.16.44",
     "@blocklet/logger": "^1.16.44",
-    "@blocklet/payment-react": "1.19.0",
+    "@blocklet/payment-react": "1.19.2",
     "@blocklet/sdk": "^1.16.44",
     "@blocklet/ui-react": "^3.0.1",
     "@blocklet/uploader": "^0.1.97",
@@ -122,7 +122,7 @@
   "devDependencies": {
     "@abtnode/types": "^1.16.44",
     "@arcblock/eslint-config-ts": "^0.3.3",
-    "@blocklet/payment-types": "1.19.0",
+    "@blocklet/payment-types": "1.19.2",
     "@types/cookie-parser": "^1.4.9",
     "@types/cors": "^2.8.19",
     "@types/debug": "^4.1.12",
@@ -168,5 +168,5 @@
       "parser": "typescript"
     }
   },
-  "gitHead": "2810263174bb900ebb5a431dc53930b08b4a8d6d"
+  "gitHead": "741c897204afc412721a942201516932bff59235"
 }

package/scripts/sdk.js

@@ -548,17 +548,249 @@ const subscriptionModule = {
   },
 };
 
+const meterModule = {
+  async createMeter() {
+    const meter = await payment.meters.create({
+      name: 'API Calls',
+      event_name: 'api_calls',
+      aggregation_method: 'sum',
+      unit: 'Token',
+      description: 'Track API usage',
+      component_did: 'zNKtcX5QyTxfM51osn5W8GMWvzabBREW2abA',
+      created_via: 'api',
+    });
+    console.log('Created meter:', meter);
+    return meter;
+  },
+
+  // 创建基于 Meter 的订阅产品和价格
+  async createMeteredSubscription() {
+    let meter;
+    try {
+      meter = await payment.meters.retrieve('api_calls');
+      if (!meter) {
+        meter = await this.createMeter();
+      }
+    } catch (error) {
+      meter = await this.createMeter();
+    }
+
+    // 创建订阅产品
+    const subscriptionProduct = await payment.products.create({
+      name: 'API Call Service',
+      description: 'API Call Service',
+    });
+
+    // 创建基于 meter 的订阅价格
+    const subscriptionPrice = await payment.prices.create({
+      product_id: subscriptionProduct.id,
+      currency_id: meter.currency_id,
+      unit_amount: '1',
+      type: 'recurring',
+      recurring: {
+        interval: 'month',
+        interval_count: 1,
+        usage_type: 'metered',
+        meter_id: meter.id,
+        aggregate_usage: 'sum',
+      },
+    });
+
+    console.log('subscriptionPrice', subscriptionPrice);
+    // 创建 checkout session
+    const subscriptionCheckout = await payment.checkout.sessions.create({
+      success_url: 'https://audiobook.com/success?session_id={CHECKOUT_SESSION_ID}',
+      cancel_url: 'https://audiobook.com/cancel',
+      mode: 'subscription',
+      line_items: [
+        {
+          price_id: subscriptionPrice.id,
+          quantity: 1,
+        },
+      ],
+    });
+
+    console.log('Metered subscription checkout:', subscriptionCheckout);
+    return { meter, subscriptionProduct, subscriptionPrice, subscriptionCheckout };
+  },
+};
+
+// 新增 Credit 相关模块
+const creditModule = {
+  // 创建 Credit 产品
+  async createCreditProduct(meter) {
+    const creditProduct = await payment.products.create({
+      name: 'API Calls Credit',
+      description: 'API Call Credit, we can ...',
+      type: 'credit',
+      prices: [
+        {
+          type: 'one_time',
+          unit_amount: '0.01',
+          currency_id: 'pc_ByBkyhRQmedm',
+          currency_options: [
+            { currency_id: 'pc_ByBkyhRQmedm', unit_amount: '0.01' },
+            { currency_id: 'pc_Dp4lY5ejkALH', unit_amount: '0.01' },
+          ],
+          lookup_key: 'api_call_credit_per_unit',
+          nickname: 'Per Unit Credit For API Call',
+          metadata: {
+            credit_config: {
+              priority: 50,
+              valid_duration_value: 0,
+              valid_duration_unit: 'days',
+              currency_id: meter.currency_id,
+              credit_amount: '1',
+            },
+            meter_id: meter.id,
+          },
+        },
+        {
+          type: 'one_time',
+          unit_amount: '8',
+          currency_id: 'pc_ByBkyhRQmedm',
+          lookup_key: 'api_calls_1000_pack',
+          nickname: '1000 Credits Pack For API Call',
+          currency_options: [
+            { currency_id: 'pc_ByBkyhRQmedm', unit_amount: '8' },
+            { currency_id: 'pc_Dp4lY5ejkALH', unit_amount: '8' },
+          ],
+          metadata: {
+            credit_config: {
+              priority: 50,
+              valid_duration_value: 0,
+              valid_duration_unit: 'days',
+              currency_id: meter.currency_id,
+              credit_amount: '1000',
+            },
+            meter_id: meter.id,
+          },
+        },
+      ],
+    });
+    console.log('Created credit product:', creditProduct.id);
+    console.log(
+      'Available prices:',
+      creditProduct.prices.map((p) => p.lookup_key)
+    );
+    return creditProduct;
+  },
+
+  // 创建支付链接
+  async createPaymentLinks() {
+    const perUnitPrice = await payment.prices.retrieve('api_call_credit_per_unit');
+    console.log('perUnitPrice', perUnitPrice);
+    // 1. 按分钟购买
+    const flexiblePaymentLink = await payment.paymentLinks.create({
+      name: 'Per Unit Credit Link',
+      currency_id: perUnitPrice.currency_id,
+      line_items: [
+        {
+          price_id: perUnitPrice.id,
+          quantity: 100,
+          adjustable_quantity: {
+            enabled: true,
+            minimum: 10,
+            maximum: 10000,
+          },
+        },
+      ],
+      metadata: {
+        credit_purchase: 'true',
+      },
+    });
+
+    const packPrice = await payment.prices.retrieve('api_calls_1000_pack');
+    console.log('packPrice', packPrice);
+    // 2. 固定套餐包
+    const packagePaymentLink = await payment.paymentLinks.create({
+      name: 'Package Credit Link',
+      currency_id: packPrice.currency_id,
+      line_items: [
+        {
+          price_id: packPrice.id,
+          quantity: 1,
+        },
+      ],
+      metadata: {
+        credit_purchase: 'true',
+      },
+    });
+
+    console.log('Flexible payment link:', flexiblePaymentLink);
+    console.log('Package payment link:', packagePaymentLink);
+    return { flexiblePaymentLink, packagePaymentLink };
+  },
+
+  // 创建/赠送 Credit Grant
+  async createCreditGrant(meter) {
+    // 方式2: 通用 Credit Grant
+    const universalCredit = await payment.creditGrants.create({
+      customer_id: 'cus_xga1PZSmiDZfz0',
+      amount: 50,
+      currency_id: meter.currency_id,
+      applicability_config: {
+        scope: {
+          price_type: 'metered',
+        },
+      },
+      category: 'promotional',
+      name: '听书时长充值',
+      metadata: {
+        purchase_source: 'mobile_app',
+      },
+    });
+    console.log('Universal credit grant:', universalCredit);
+    return { universalCredit };
+  },
+
+  // 上报 Credit 消耗用量
+  async reportUsage(customerId, minutes, sessionContext) {
+    const creditBalance = await payment.creditGrants.summary({
+      customer_id: customerId,
+    });
+    console.log('creditBalance', creditBalance);
+    const meterEvent = await payment.meterEvents.create({
+      event_name: 'api_calls',
+      timestamp: Math.floor(Date.now() / 1000),
+      payload: {
+        customer_id: customerId,
+        value: String(minutes),
+        subscription_id: sessionContext.subscriptionId || undefined,
+      },
+      identifier: `${customerId}_${sessionContext.sessionId}_${Date.now()}`,
+      metadata: {
+        session_id: sessionContext.sessionId,
+      },
+    });
+
+    return {
+      event_id: meterEvent.id,
+      identifier: meterEvent.identifier,
+      timestamp: meterEvent.timestamp,
+    };
+  },
+};
+
 const testModules = {
   checkout: checkoutModule,
   payment: paymentModule,
   product: productModule,
   subscription: subscriptionModule,
+  meter: meterModule,
+  credit: creditModule,
 };
 
 // 测试入口
 async function runTest() {
   payment.environments.setTestMode(true);
-  await testModules.checkout.createBatchSubscriptionWithCustomField();
+  const { meter } = await testModules.meter.createMeteredSubscription();
+  // await testModules.credit.createCreditProduct(meter);
+  // await testModules.credit.createPaymentLinks();
+  // await testModules.credit.createCreditGrant(meter);
+  await testModules.credit.reportUsage('cus_xga1PZSmiDZfz0', 2, {
+    sessionId: 'session_123',
+  });
 }
 
 async function main() {

package/src/app.tsx

@@ -27,6 +27,7 @@ const CustomerSubscriptionDetail = React.lazy(() => import('./pages/customer/sub
 const CustomerSubscriptionEmbed = React.lazy(() => import('./pages/customer/subscription/embed'));
 const CustomerSubscriptionChangePlan = React.lazy(() => import('./pages/customer/subscription/change-plan'));
 const CustomerSubscriptionChangePayment = React.lazy(() => import('./pages/customer/subscription/change-payment'));
+const CustomerCreditGrantDetail = React.lazy(() => import('./pages/customer/credit-grant/detail'));
 const CustomerRecharge = React.lazy(() => import('./pages/customer/recharge/subscription'));
 const CustomerPayoutDetail = React.lazy(() => import('./pages/customer/payout/detail'));
 const IntegrationsPage = React.lazy(() => import('./pages/integrations'));
@@ -149,6 +150,15 @@ function App() {
                 </UserLayout>
               }
             />
+            <Route
+              key="customer-credit-grant"
+              path="/customer/credit-grant/:id"
+              element={
+                <UserLayout>
+                  <CustomerCreditGrantDetail />
+                </UserLayout>
+              }
+            />
             <Route key="customer-fallback" path="/customer/*" element={<Navigate to="/customer" />} />,
             <Route path="*" element={<Navigate to="/" />} />
           </Routes>

package/src/components/collapse.tsx

@@ -12,6 +12,7 @@ type Props = {
   value?: string;
   onChange?: (value: string, expanded: boolean) => void;
   lazy?: boolean;
+  card?: boolean;
 };
 
 export default function IconCollapse(rawProps: Props) {
@@ -24,6 +25,7 @@ export default function IconCollapse(rawProps: Props) {
       addons: null,
       style: {},
       lazy: true,
+      card: false,
     },
     rawProps
   );
@@ -54,6 +56,12 @@ export default function IconCollapse(rawProps: Props) {
           fontWeight: 500,
           color: 'text.primary',
           '& :hover': { color: 'primary.main' },
+          ...(props.card && {
+            borderRadius: 1,
+            padding: 1,
+            pl: 2,
+            backgroundColor: 'grey.100',
+          }),
           ...props.style,
         }}>
         <Box>{typeof props.trigger === 'function' ? props.trigger(expanded) : props.trigger}</Box>
@@ -66,7 +74,9 @@ export default function IconCollapse(rawProps: Props) {
           {props.addons} {expanded ? <ExpandLessOutlined /> : <ExpandMoreOutlined />}
         </Stack>
       </Stack>
-      <Collapse in={expanded}>{expanded || props.lazy ? props.children : null}</Collapse>
+      <Collapse in={expanded} sx={{ width: '100%' }}>
+        {expanded || props.lazy ? props.children : null}
+      </Collapse>
     </>
   );
 }

package/src/components/conditional-section.tsx

@@ -0,0 +1,87 @@
+import { Box } from '@mui/material';
+import { useState, ReactNode, useEffect, createContext, useContext, useMemo, useRef, useCallback } from 'react';
+
+const ConditionalSectionContext = createContext<{
+  hideRender: (hide?: boolean) => void;
+} | null>(null);
+
+// 导出hook供子组件使用
+export const useConditionalSection = () => {
+  const context = useContext(ConditionalSectionContext);
+  return context;
+};
+
+interface ConditionalSectionProps {
+  skeleton: boolean;
+  children: ReactNode;
+  skeletonComponent?: ReactNode;
+}
+
+/**
+ * 条件渲染组件 - 完全防闪现版本
+ *
+ * 彻底解决闪现问题的方案：
+ * 1. skeleton=true 时显示骨架屏组件
+ * 2. skeleton=false 时完全隐藏(display: none)渲染子组件，让其执行逻辑
+ * 3. 等待子组件执行完毕，如果没有调用hideRender则显示
+ * 4. 整个过程用户看不到任何闪现
+ *
+ * 使用方式：
+ * - 在任意深度的子组件中调用 useConditionalSection()?.hideRender()
+ */
+export default function ConditionalSection({ skeleton, children, skeletonComponent = null }: ConditionalSectionProps) {
+  const [renderState, setRenderState] = useState<'hidden' | 'visible' | 'none'>('hidden');
+  const timerRef = useRef<NodeJS.Timeout | null>(null);
+
+  const handleHideRender = useCallback((hide: boolean = true) => {
+    if (timerRef.current) {
+      clearTimeout(timerRef.current);
+      timerRef.current = null;
+    }
+    setRenderState(hide ? 'none' : 'visible');
+  }, []);
+
+  const contextValue = useMemo(() => ({ hideRender: handleHideRender }), [handleHideRender]);
+
+  useEffect(() => {
+    if (!skeleton) {
+      timerRef.current = setTimeout(() => {
+        setRenderState('visible');
+        timerRef.current = null;
+      }, 3000);
+    }
+
+    // 清理定时器
+    return () => {
+      if (timerRef.current) {
+        clearTimeout(timerRef.current);
+        timerRef.current = null;
+      }
+    };
+  }, [skeleton]);
+
+  if (skeleton) {
+    return skeletonComponent;
+  }
+
+  if (renderState === 'none') {
+    return null;
+  }
+
+  return (
+    <ConditionalSectionContext.Provider value={contextValue}>
+      <Box
+        sx={{
+          position: renderState === 'hidden' ? 'absolute' : 'static',
+          left: renderState === 'hidden' ? '-9999px' : 'auto',
+          top: renderState === 'hidden' ? '-9999px' : 'auto',
+          visibility: renderState === 'hidden' ? 'hidden' : 'visible',
+          width: renderState === 'hidden' ? '0' : 'auto',
+          height: renderState === 'hidden' ? '0' : 'auto',
+          overflow: 'hidden',
+        }}>
+        {children}
+      </Box>
+    </ConditionalSectionContext.Provider>
+  );
+}