payment-kit 1.18.56 → 1.19.1

package/api/src/store/models/meter-event.ts

@@ -0,0 +1,423 @@
+/* eslint-disable @typescript-eslint/lines-between-class-members */
+import {
+  CreationOptional,
+  DataTypes,
+  InferAttributes,
+  InferCreationAttributes,
+  Model,
+  Op,
+  QueryTypes,
+  WhereOptions,
+} from 'sequelize';
+import type { LiteralUnion } from 'type-fest';
+
+import { BN } from '@ocap/util';
+import { createEvent } from '../../libs/audit';
+import { createIdGenerator } from '../../libs/util';
+import { GroupedBN, GroupedStrList, MeterEventPayload, MeterEventStatus } from './types';
+import { Customer } from './customer';
+import { Subscription, type TSubscription } from './subscription';
+import { Meter, type TMeter } from './meter';
+import { PaymentCurrency, TPaymentCurrency } from './payment-currency';
+
+export const nextMeterEventId = createIdGenerator('mevt', 14);
+
+type TMeterEventExpanded = MeterEvent & {
+  customer: Customer;
+  subscription?: TSubscription;
+  meter?: TMeter;
+  paymentCurrency: TPaymentCurrency;
+};
+
+export class MeterEvent extends Model<InferAttributes<MeterEvent>, InferCreationAttributes<MeterEvent>> {
+  declare id: CreationOptional<string>;
+  declare event_name: string;
+  declare payload: MeterEventPayload;
+  declare identifier: string; // 防重复的唯一标识
+  declare timestamp: number;
+  declare livemode: boolean;
+  declare status: MeterEventStatus;
+  declare processed_at?: number; // 处理时间
+  declare attempt_count: number; // 重试次数
+  declare next_attempt?: number; // 下次尝试时间
+  declare credit_consumed: string; // 已消费的credit数量
+  declare credit_pending: string; // 待消费的credit数量（债务）
+  declare metadata?: Record<string, any>;
+
+  // 审计字段
+  declare created_by?: string;
+  declare created_via: LiteralUnion<'api' | 'dashboard' | 'webhook' | 'batch', string>;
+
+  declare created_at: CreationOptional<Date>;
+  declare updated_at: CreationOptional<Date>;
+
+  public static readonly GENESIS_ATTRIBUTES = {
+    id: {
+      type: DataTypes.STRING(18),
+      primaryKey: true,
+      allowNull: false,
+      defaultValue: nextMeterEventId,
+    },
+    event_name: {
+      type: DataTypes.STRING(128),
+      allowNull: false,
+    },
+    timestamp: {
+      type: DataTypes.INTEGER,
+      allowNull: false,
+    },
+    payload: {
+      type: DataTypes.JSON,
+      allowNull: false,
+      validate: {
+        hasRequiredFields(value: any) {
+          if (!value || typeof value !== 'object') {
+            throw new Error('Payload must be an object');
+          }
+          if (!value.customer_id || !value.value) {
+            throw new Error('Payload must contain customer_id, value');
+          }
+        },
+      },
+    },
+    identifier: {
+      type: DataTypes.STRING(255),
+      allowNull: false,
+      unique: true, // 确保幂等性
+    },
+    livemode: {
+      type: DataTypes.BOOLEAN,
+      allowNull: false,
+    },
+    status: {
+      type: DataTypes.ENUM('pending', 'processing', 'requires_action', 'requires_capture', 'completed', 'canceled'),
+      defaultValue: 'pending',
+      allowNull: false,
+    },
+    attempt_count: {
+      type: DataTypes.INTEGER,
+      defaultValue: 0,
+      allowNull: false,
+    },
+    next_attempt: {
+      type: DataTypes.INTEGER,
+      allowNull: true,
+    },
+    processed_at: {
+      type: DataTypes.INTEGER,
+      allowNull: true,
+    },
+    credit_consumed: {
+      type: DataTypes.STRING(40),
+      defaultValue: '0',
+      allowNull: false,
+    },
+    credit_pending: {
+      type: DataTypes.STRING(40),
+      defaultValue: '0',
+      allowNull: false,
+    },
+    metadata: {
+      type: DataTypes.JSON,
+      allowNull: true,
+    },
+    created_by: {
+      type: DataTypes.STRING(40),
+      allowNull: true,
+    },
+    created_via: {
+      type: DataTypes.ENUM('api', 'dashboard', 'webhook', 'batch'),
+      allowNull: false,
+    },
+    created_at: {
+      type: DataTypes.DATE,
+      defaultValue: DataTypes.NOW,
+      allowNull: false,
+    },
+    updated_at: {
+      type: DataTypes.DATE,
+      defaultValue: DataTypes.NOW,
+      allowNull: false,
+    },
+  };
+
+  // 标记为成功完成
+  public async markAsCompleted(): Promise<void> {
+    this.status = 'completed';
+    this.processed_at = Math.floor(Date.now() / 1000);
+    this.next_attempt = undefined;
+    // 清除错误信息
+    if (this.metadata?.last_error) {
+      this.metadata = {
+        ...this.metadata,
+        last_error: undefined,
+        failed_at: undefined,
+      };
+    }
+    await this.save();
+  }
+
+  // 标记为处理中
+  public async markAsProcessing(): Promise<void> {
+    this.status = 'processing';
+    await this.save();
+  }
+
+  // 标记为需要重试 (参考 payment.ts 的重试机制)
+  public async markAsRequiresCapture(errorMessage: string, nextAttemptTime: number): Promise<void> {
+    this.status = 'requires_capture';
+    this.attempt_count += 1;
+    this.next_attempt = nextAttemptTime;
+    this.metadata = {
+      ...this.metadata,
+      last_error: errorMessage,
+      failed_at: Math.floor(Date.now() / 1000),
+    };
+    await this.save();
+  }
+
+  // 标记为需要手动处理
+  public async markAsRequiresAction(errorMessage: string): Promise<void> {
+    this.status = 'requires_action';
+    this.metadata = {
+      ...this.metadata,
+      last_error: errorMessage,
+      failed_at: Math.floor(Date.now() / 1000),
+      requires_manual_intervention: true,
+    };
+    await this.save();
+  }
+
+  // 标记为取消
+  public async markAsCanceled(reason: string): Promise<void> {
+    this.status = 'canceled';
+    this.metadata = {
+      ...this.metadata,
+      cancel_reason: reason,
+      canceled_at: Math.floor(Date.now() / 1000),
+    };
+    await this.save();
+  }
+
+  // 获取客户ID
+  public getCustomerId(): string {
+    return this.payload.customer_id;
+  }
+
+  // 获取使用量
+  public getValue(): string {
+    return this.payload.value;
+  }
+
+  // 获取订阅ID
+  public getSubscriptionId(): string | undefined {
+    return this.payload.subscription_id;
+  }
+
+  public static initialize(sequelize: any) {
+    this.init(this.GENESIS_ATTRIBUTES, {
+      sequelize,
+      modelName: 'MeterEvent',
+      tableName: 'meter_events',
+      createdAt: 'created_at',
+      updatedAt: 'updated_at',
+      indexes: [{ fields: ['identifier'], unique: true }, { fields: ['status'] }, { fields: ['event_name'] }],
+      hooks: {
+        afterCreate: (model: MeterEvent, options) =>
+          createEvent('MeterEvent', 'billing.meter_event.created', model, options).catch(console.error),
+      },
+    });
+  }
+
+  // 批量处理未处理的事件
+  public static async processUnprocessedEvents(eventName?: string, limit: number = 100): Promise<MeterEvent[]> {
+    const whereClause: any = {
+      status: ['pending', 'requires_capture'],
+    };
+    if (eventName) {
+      whereClause.event_name = eventName;
+    }
+
+    const events = await this.findAll({
+      where: whereClause,
+      order: [['created_at', 'ASC']],
+      limit,
+    });
+
+    return events;
+  }
+
+  // 检查事件是否已存在（防重复）
+  public static async isEventExists(identifier: string): Promise<boolean> {
+    const count = await this.count({
+      where: { identifier },
+    });
+    return count > 0;
+  }
+
+  // 获取事件统计
+  public static async getEventStats(
+    eventName: string,
+    startTime?: Date,
+    endTime?: Date
+  ): Promise<{
+    total_events: number;
+    processed_events: number;
+    pending_events: number;
+    total_value: number;
+  }> {
+    const whereClause: any = { event_name: eventName };
+
+    if (startTime || endTime) {
+      whereClause.created_at = {};
+      if (startTime) {
+        whereClause.created_at[Op.gte] = startTime;
+      }
+      if (endTime) {
+        whereClause.created_at[Op.lte] = endTime;
+      }
+    }
+
+    const [totalEvents, processedEvents, totalValue] = await Promise.all([
+      this.count({ where: whereClause }),
+      this.count({ where: { ...whereClause, status: 'completed' } }),
+      // @ts-ignore
+      this.sequelize.query(
+        `SELECT COALESCE(SUM(CAST(payload->>'value' AS DECIMAL)), 0) as total 
+         FROM meter_events 
+         WHERE event_name = :eventName 
+         ${startTime ? 'AND created_at >= :startTime' : ''}
+         ${endTime ? 'AND created_at <= :endTime' : ''}`,
+        {
+          replacements: {
+            eventName,
+            startTime: startTime?.toISOString(),
+            endTime: endTime?.toISOString(),
+          },
+          type: QueryTypes.SELECT,
+        }
+      ),
+    ]);
+
+    return {
+      total_events: totalEvents,
+      processed_events: processedEvents,
+      pending_events: totalEvents - processedEvents,
+      total_value: (totalValue as any)?.[0]?.total || 0,
+    };
+  }
+
+  public static async expand(
+    events: MeterEvent[],
+    livemode: boolean = true,
+    options: { customer?: boolean; subscription?: boolean; meter?: boolean } = {}
+  ): Promise<MeterEvent[]> {
+    const { customer = true, subscription = true, meter = true } = options;
+
+    let customers: Customer[] = [];
+    let subscriptions: TSubscription[] = [];
+    let meters: TMeter[] = [];
+
+    if (customer) {
+      const customerIds = events.map((x) => x.payload.customer_id);
+      customers = await Customer.findAll({
+        where: { [Op.or]: [{ id: { [Op.in]: customerIds } }, { did: { [Op.in]: customerIds } }] },
+      });
+    }
+    if (subscription) {
+      const subscriptionIds = events.map((x) => x.payload?.subscription_id).filter(Boolean) as string[];
+      subscriptions = await Subscription.findAll({
+        where: {
+          id: {
+            [Op.in]: subscriptionIds,
+          },
+        },
+      });
+    }
+    if (meter) {
+      const eventNames = events.map((x) => x.event_name);
+      meters = await Meter.findAll({
+        where: {
+          event_name: {
+            [Op.in]: eventNames,
+          },
+          livemode,
+        },
+      });
+    }
+
+    return events.map((x) => ({
+      ...x.toJSON(),
+      customer: customers.find((c) => c.id === x.payload.customer_id),
+      subscription: subscriptions.find((s) => s.id === x.payload.subscription_id),
+      meter: meters.find((m) => m.event_name === x.event_name),
+    })) as TMeterEventExpanded[];
+  }
+
+  private static async _getPendingAmounts(
+    where: WhereOptions<MeterEvent>,
+    searchCurrencyId?: string
+  ): Promise<[GroupedBN, GroupedStrList, MeterEvent[]]> {
+    const events = await this.findAll({ where });
+    const summary: GroupedBN = {};
+    const detail: GroupedStrList = {};
+
+    await Promise.all(
+      events.map(async (event) => {
+        const meter = await Meter.getMeterByEventName(event.event_name, event.livemode);
+        if (!meter) {
+          return;
+        }
+        const paymentCurrency = await PaymentCurrency.findByPk(meter.currency_id);
+        if (!paymentCurrency) {
+          return;
+        }
+        const currencyId = meter.currency_id as string;
+        if (searchCurrencyId && searchCurrencyId !== currencyId) {
+          return;
+        }
+        if (!detail[currencyId]) {
+          detail[currencyId] = [];
+        }
+        summary[currencyId] = new BN(summary[currencyId] || '0').add(new BN(event.credit_pending)).toString();
+        detail[currencyId]!.push(event.id);
+      })
+    );
+
+    return [summary, detail, events];
+  }
+
+  public static getPendingAmounts({
+    subscriptionId,
+    livemode,
+    currencyId,
+    status = ['requires_action', 'requires_capture'],
+    customerId,
+  }: {
+    subscriptionId?: string;
+    livemode?: boolean;
+    currencyId?: string;
+    status?: MeterEventStatus | MeterEventStatus[];
+    customerId?: string;
+  }): Promise<[GroupedBN, GroupedStrList, MeterEvent[]]> {
+    const where: any = {
+      status: {
+        [Op.in]: ['pending', 'requires_capture', 'requires_action'],
+      },
+      livemode: livemode ?? true,
+    };
+    if (status) {
+      where.status = Array.isArray(status) ? { [Op.in]: status } : status;
+    }
+    if (subscriptionId) {
+      where['payload.subscription_id'] = subscriptionId;
+    }
+    if (customerId) {
+      where['payload.customer_id'] = customerId;
+    }
+
+    return this._getPendingAmounts(where, currencyId);
+  }
+}
+
+export type TMeterEvent = InferAttributes<MeterEvent>;

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

@@ -0,0 +1,176 @@
+/* eslint-disable @typescript-eslint/lines-between-class-members */
+import { CreationOptional, DataTypes, InferAttributes, InferCreationAttributes, Model } from 'sequelize';
+import type { LiteralUnion } from 'type-fest';
+
+import { createEvent } from '../../libs/audit';
+import { createIdGenerator } from '../../libs/util';
+import type { TPaymentCurrency } from './payment-currency';
+
+export const nextMeterId = createIdGenerator('mtr', 14);
+
+export type TMeterExpanded = TMeter & {
+  paymentCurrency: TPaymentCurrency;
+};
+
+export class Meter extends Model<InferAttributes<Meter>, InferCreationAttributes<Meter>> {
+  declare id: CreationOptional<string>;
+  declare object: CreationOptional<string>;
+  declare name: string;
+  declare event_name: string;
+  declare aggregation_method: LiteralUnion<'sum' | 'count' | 'last', string>;
+  declare status: LiteralUnion<'active' | 'inactive', string>;
+  declare unit: string;
+  declare description?: string;
+  declare component_did?: string;
+  declare livemode: boolean;
+
+  declare metadata?: Record<string, any>;
+  declare currency_id?: string;
+
+  // 审计字段
+  declare created_by?: string;
+  declare updated_by?: string;
+  declare created_via: LiteralUnion<'api' | 'dashboard' | 'portal', string>;
+
+  declare created_at: CreationOptional<Date>;
+  declare updated_at: CreationOptional<Date>;
+
+  public static readonly GENESIS_ATTRIBUTES = {
+    id: {
+      type: DataTypes.STRING(18),
+      primaryKey: true,
+      allowNull: false,
+      defaultValue: nextMeterId,
+    },
+    object: {
+      type: DataTypes.STRING(32),
+      defaultValue: 'meter',
+      allowNull: false,
+    },
+    name: {
+      type: DataTypes.STRING(255),
+      allowNull: false,
+    },
+    event_name: {
+      type: DataTypes.STRING(128),
+      allowNull: false,
+      unique: true,
+    },
+    aggregation_method: {
+      type: DataTypes.ENUM('sum', 'count', 'last'),
+      defaultValue: 'sum',
+      allowNull: false,
+    },
+    status: {
+      type: DataTypes.ENUM('active', 'inactive'),
+      defaultValue: 'active',
+      allowNull: false,
+    },
+    unit: {
+      type: DataTypes.STRING(32),
+      allowNull: false,
+    },
+    description: {
+      type: DataTypes.TEXT,
+      allowNull: true,
+    },
+    component_did: {
+      type: DataTypes.STRING(40),
+      allowNull: true,
+    },
+    currency_id: {
+      type: DataTypes.STRING(40),
+      allowNull: true,
+    },
+    livemode: {
+      type: DataTypes.BOOLEAN,
+      allowNull: false,
+    },
+    metadata: {
+      type: DataTypes.JSON,
+      allowNull: true,
+    },
+    created_by: {
+      type: DataTypes.STRING(40),
+      allowNull: true,
+    },
+    updated_by: {
+      type: DataTypes.STRING(40),
+      allowNull: true,
+    },
+    created_via: {
+      type: DataTypes.ENUM('api', 'dashboard', 'portal'),
+      allowNull: false,
+    },
+    created_at: {
+      type: DataTypes.DATE,
+      defaultValue: DataTypes.NOW,
+      allowNull: false,
+    },
+    updated_at: {
+      type: DataTypes.DATE,
+      defaultValue: DataTypes.NOW,
+      allowNull: false,
+    },
+  };
+
+  public static initialize(sequelize: any) {
+    this.init(this.GENESIS_ATTRIBUTES, {
+      sequelize,
+      modelName: 'Meter',
+      tableName: 'meters',
+      createdAt: 'created_at',
+      updatedAt: 'updated_at',
+      indexes: [{ fields: ['event_name'] }, { fields: ['currency_id'] }],
+      hooks: {
+        afterCreate: (model: Meter, options) =>
+          createEvent('Meter', 'meter.created', model, options).catch(console.error),
+        afterUpdate: (model: Meter, options) =>
+          createEvent('Meter', 'meter.updated', model, options).catch(console.error),
+        afterDestroy: (model: Meter, options) =>
+          createEvent('Meter', 'meter.deleted', model, options).catch(console.error),
+      },
+    });
+  }
+
+  public static associate(models: any) {
+    this.hasMany(models.CreditTransaction, {
+      foreignKey: 'meter_id',
+      as: 'transactions',
+    });
+
+    this.hasOne(models.PaymentCurrency, {
+      sourceKey: 'currency_id',
+      foreignKey: 'id',
+      as: 'paymentCurrency',
+    });
+  }
+
+  public static getMeterByEventName(eventName: string, livemode?: boolean): Promise<Meter | null> {
+    const whereClause: any = { event_name: eventName, livemode: true };
+    if (livemode !== undefined) {
+      whereClause.livemode = livemode;
+    }
+    return this.findOne({ where: whereClause });
+  }
+
+  public static async getMetricsForMeter(meterId: string, customerId?: string) {
+    // @ts-ignore
+    const { CreditTransaction } = this.sequelize.models;
+    const whereClause: any = { meter_id: meterId };
+    if (customerId) {
+      whereClause.customer_id = customerId;
+    }
+
+    // @ts-ignore
+    const totalUsage = await CreditTransaction.sum('credit_amount', {
+      where: whereClause,
+    });
+
+    return {
+      total_usage: totalUsage || 0,
+    };
+  }
+}
+
+export type TMeter = InferAttributes<Meter>;

package/api/src/store/models/payment-currency.ts

@@ -9,7 +9,8 @@ import {
   Op,
   QueryTypes,
 } from 'sequelize';
-
+import { getUrl } from '@blocklet/sdk';
+import type { LiteralUnion } from 'type-fest';
 import { createIdGenerator } from '../../libs/util';
 import { VaultConfig } from './types';
 
@@ -43,6 +44,7 @@ export class PaymentCurrency extends Model<InferAttributes<PaymentCurrency>, Inf
   declare created_at: CreationOptional<Date>;
   declare updated_at: CreationOptional<Date>;
   declare vault_config?: VaultConfig;
+  declare type: LiteralUnion<'standard' | 'credit', string>;
 
   public static readonly GENESIS_ATTRIBUTES = {
     id: {
@@ -129,21 +131,31 @@ export class PaymentCurrency extends Model<InferAttributes<PaymentCurrency>, Inf
   };
 
   public static initialize(sequelize: any) {
-    this.init(PaymentCurrency.GENESIS_ATTRIBUTES, {
-      sequelize,
-      modelName: 'PaymentCurrency',
-      tableName: 'payment_currencies',
-      createdAt: 'created_at',
-      updatedAt: 'updated_at',
-      defaultScope: {
-        attributes: { exclude: ['vault_config'] },
-      },
-      scopes: {
-        withVaultConfig: {
-          attributes: { include: ['vault_config'] },
+    this.init(
+      {
+        ...PaymentCurrency.GENESIS_ATTRIBUTES,
+        type: {
+          type: DataTypes.ENUM('standard', 'credit'),
+          defaultValue: 'standard',
+          allowNull: false,
         },
       },
-    });
+      {
+        sequelize,
+        modelName: 'PaymentCurrency',
+        tableName: 'payment_currencies',
+        createdAt: 'created_at',
+        updatedAt: 'updated_at',
+        defaultScope: {
+          attributes: { exclude: ['vault_config'] },
+        },
+        scopes: {
+          withVaultConfig: {
+            attributes: { include: ['vault_config'] },
+          },
+        },
+      }
+    );
   }
 
   public static associate(models: any) {
@@ -190,6 +202,46 @@ export class PaymentCurrency extends Model<InferAttributes<PaymentCurrency>, Inf
     );
     return count > 0;
   }
+  public static async createForMeter(meter: any, paymentMethodId: string) {
+    const existingCurrency = await this.findOne({
+      where: {
+        type: 'credit',
+        symbol: meter.unit,
+        livemode: meter.livemode || false,
+      },
+    });
+
+    if (existingCurrency) {
+      return existingCurrency;
+    }
+    const currency = await this.create({
+      type: 'credit',
+      payment_method_id: paymentMethodId,
+      name: meter.unit,
+      description: `Credit for ${meter.unit}`,
+      symbol: meter.unit,
+      logo: getUrl('/methods/arcblock.png'), // 默认credit图标
+      decimal: 2,
+      maximum_precision: 2,
+      minimum_payment_amount: '1',
+      maximum_payment_amount: '100000000000',
+      active: true,
+      livemode: meter.livemode || false,
+      is_base_currency: false,
+      locked: false,
+      metadata: {
+        meter_id: meter.id,
+        meter_event_name: meter.event_name,
+        created_by_meter: true,
+      },
+    });
+
+    return currency;
+  }
+
+  public isCredit(): boolean {
+    return this.type === 'credit';
+  }
 }
 
 export type TPaymentCurrency = InferAttributes<PaymentCurrency>;