payment-kit 1.18.56 → 1.19.1

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.18.56
+version: 1.19.1
 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,9 +1,8 @@
 {
   "name": "payment-kit",
-  "version": "1.18.56",
+  "version": "1.19.1",
   "scripts": {
     "dev": "blocklet dev --open",
-    "eject": "vite eject",
     "lint": "tsc --noEmit && eslint src api/src --ext .mjs,.js,.jsx,.ts,.tsx",
     "lint:fix": "pnpm run lint --fix",
     "format": "prettier -w src",
@@ -47,116 +46,116 @@
     "@abtnode/cron": "^1.16.44",
     "@arcblock/did": "^1.20.14",
     "@arcblock/did-auth-storage-nedb": "^1.7.1",
-    "@arcblock/did-connect": "^2.13.66",
+    "@arcblock/did-connect": "^3.0.1",
     "@arcblock/did-util": "^1.20.14",
     "@arcblock/jwt": "^1.20.14",
-    "@arcblock/ux": "^2.13.66",
+    "@arcblock/ux": "^3.0.1",
     "@arcblock/validator": "^1.20.14",
-    "@blocklet/did-space-js": "^1.0.60",
+    "@blocklet/did-space-js": "^1.0.62",
     "@blocklet/js-sdk": "^1.16.44",
     "@blocklet/logger": "^1.16.44",
-    "@blocklet/payment-react": "1.18.56",
+    "@blocklet/payment-react": "1.19.1",
     "@blocklet/sdk": "^1.16.44",
-    "@blocklet/ui-react": "^2.13.66",
-    "@blocklet/uploader": "^0.1.95",
+    "@blocklet/ui-react": "^3.0.1",
+    "@blocklet/uploader": "^0.1.97",
     "@blocklet/xss": "^0.1.36",
-    "@mui/icons-material": "^5.16.6",
-    "@mui/lab": "^5.0.0-alpha.173",
-    "@mui/material": "^5.16.6",
-    "@mui/system": "^5.16.6",
+    "@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.20.14",
     "@ocap/client": "^1.20.14",
     "@ocap/mcrypto": "^1.20.14",
     "@ocap/util": "^1.20.14",
     "@ocap/wallet": "^1.20.14",
-    "@stripe/react-stripe-js": "^2.7.3",
+    "@stripe/react-stripe-js": "^2.9.0",
     "@stripe/stripe-js": "^2.4.0",
-    "ahooks": "^3.8.0",
-    "axios": "^1.7.5",
-    "body-parser": "^1.20.2",
+    "ahooks": "^3.8.5",
+    "axios": "^1.10.0",
+    "body-parser": "^1.20.3",
     "cls-hooked": "^4.2.2",
-    "cookie-parser": "^1.4.6",
+    "cookie-parser": "^1.4.7",
     "copy-to-clipboard": "^3.3.3",
     "cors": "^2.8.5",
     "date-fns": "^3.6.0",
-    "dayjs": "^1.11.12",
-    "debug": "^4.3.6",
+    "dayjs": "^1.11.13",
+    "debug": "^4.4.1",
     "dotenv-flow": "^3.3.0",
-    "ethers": "^6.13.5",
-    "express": "^4.19.2",
+    "ethers": "^6.14.4",
+    "express": "^4.21.2",
     "express-async-errors": "^3.1.1",
     "express-history-api-fallback": "^2.2.1",
-    "fastq": "^1.17.1",
+    "fastq": "^1.19.1",
     "flat": "^5.0.2",
-    "google-libphonenumber": "^3.2.38",
+    "google-libphonenumber": "^3.2.42",
     "html2canvas": "^1.4.1",
     "iframe-resizer-react": "^1.1.1",
-    "joi": "^17.12.2",
-    "json-stable-stringify": "^1.1.1",
+    "joi": "17.12.2",
+    "json-stable-stringify": "^1.3.0",
     "jspdf": "^2.5.2",
     "lodash": "^4.17.21",
     "morgan": "^1.10.0",
     "mui-daterange-picker": "^1.0.5",
-    "nanoid": "3",
+    "nanoid": "^3.3.11",
     "p-all": "3.0.0",
-    "p-wait-for": "3",
+    "p-wait-for": "^3.2.0",
     "pretty-ms-i18n": "^1.0.3",
-    "react": "18.2.0",
-    "react-dom": "18.2.0",
-    "react-error-boundary": "^4.0.13",
-    "react-hook-form": "^7.52.1",
+    "react": "^19.1.0",
+    "react-dom": "^19.1.0",
+    "react-error-boundary": "^4.1.2",
+    "react-hook-form": "^7.58.1",
     "react-international-phone": "^3.1.2",
-    "react-router-dom": "^6.25.1",
-    "recharts": "^2.12.7",
+    "react-router-dom": "^6.30.1",
+    "recharts": "^2.15.4",
     "rimraf": "^3.0.2",
-    "sequelize": "^6.37.3",
+    "sequelize": "^6.37.7",
     "sql-where-parser": "^2.2.1",
     "sqlite3": "^5.1.7",
     "stripe": "^13.11.0",
-    "typewriter-effect": "^2.21.0",
+    "typewriter-effect": "^2.22.0",
     "ufo": "^1.6.1",
-    "umzug": "^3.8.1",
+    "umzug": "^3.8.2",
     "use-bus": "^2.5.2",
-    "validator": "^13.12.0",
+    "validator": "^13.15.15",
     "web3": "^4.16.0"
   },
   "devDependencies": {
     "@abtnode/types": "^1.16.44",
     "@arcblock/eslint-config-ts": "^0.3.3",
-    "@blocklet/payment-types": "1.18.56",
-    "@types/cookie-parser": "^1.4.7",
-    "@types/cors": "^2.8.17",
+    "@blocklet/payment-types": "1.19.1",
+    "@types/cookie-parser": "^1.4.9",
+    "@types/cors": "^2.8.19",
     "@types/debug": "^4.1.12",
     "@types/dotenv-flow": "^3.3.3",
-    "@types/express": "^4.17.21",
-    "@types/node": "^18.19.42",
-    "@types/react": "^18.3.3",
-    "@types/react-dom": "^18.3.0",
-    "@vitejs/plugin-react": "^4.3.1",
+    "@types/express": "^4.17.23",
+    "@types/node": "^18.19.112",
+    "@types/react": "^18.3.23",
+    "@types/react-dom": "^18.3.7",
+    "@vitejs/plugin-react": "^4.6.0",
     "babel-plugin-lodash": "^3.3.4",
     "bumpp": "^8.2.1",
     "cross-env": "^7.0.3",
-    "eslint": "^8.57.0",
+    "eslint": "^8.57.1",
     "import-sort-style-module": "^6.0.0",
     "jest": "^29.7.0",
     "lint-staged": "^12.5.0",
     "nodemon": "^2.0.22",
     "npm-run-all": "^4.1.5",
-    "prettier": "^3.3.3",
+    "prettier": "^3.6.0",
     "prettier-plugin-import-sort": "^0.0.7",
-    "rollup-plugin-visualizer": "^5.12.0",
-    "ts-jest": "^29.2.5",
+    "rollup-plugin-visualizer": "^6.0.3",
+    "ts-jest": "^29.4.0",
     "ts-node": "^10.9.2",
-    "tsx": "^4.19.2",
-    "type-fest": "^4.23.0",
-    "typescript": "^5.5.4",
-    "vite": "^5.3.5",
-    "vite-node": "^2.0.4",
+    "tsx": "^4.20.3",
+    "type-fest": "^4.41.0",
+    "typescript": "5.5.4",
+    "vite": "^7.0.0",
+    "vite-node": "^3.2.4",
     "vite-plugin-babel-import": "^2.0.5",
     "vite-plugin-blocklet": "^0.9.33",
-    "vite-plugin-node-polyfills": "^0.21.0",
-    "vite-plugin-svgr": "^4.2.0",
-    "vite-tsconfig-paths": "^4.3.2",
+    "vite-plugin-node-polyfills": "^0.23.0",
+    "vite-plugin-svgr": "^4.3.0",
+    "vite-tsconfig-paths": "^5.1.4",
     "zx": "^7.2.3"
   },
   "importSort": {
@@ -169,5 +168,5 @@
       "parser": "typescript"
     }
   },
-  "gitHead": "9fd0235186e07388337cf1a57b257f97de8dd4c3"
+  "gitHead": "48d5719c8ce4e89a16f8dd576ff8f72072e3909e"
 }

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() {