payment-kit 1.19.0 → 1.19.1

package/api/src/routes/credit-transactions.ts

@@ -0,0 +1,208 @@
+import { Router } from 'express';
+import Joi from 'joi';
+
+import { Op } from 'sequelize';
+import { createListParamSchema, getOrder, getWhereFromKvQuery } from '../libs/api';
+import logger from '../libs/logger';
+import { authenticate } from '../libs/security';
+import { CreditTransaction, Customer, CreditGrant, Meter, Subscription, PaymentCurrency } from '../store/models';
+
+const router = Router();
+const authMine = authenticate<CreditTransaction>({ component: true, roles: ['owner', 'admin'], mine: true });
+const authPortal = authenticate<CreditTransaction>({
+  component: true,
+  roles: ['owner', 'admin'],
+  record: {
+    // @ts-ignore
+    model: CreditTransaction,
+    field: 'customer_id',
+  },
+});
+
+const listSchema = createListParamSchema<{
+  customer_id?: string;
+  subscription_id?: string;
+  credit_grant_id?: string;
+  start?: number;
+  end?: number;
+  source?: string;
+}>({
+  customer_id: Joi.string().empty(''),
+  subscription_id: Joi.string().empty(''),
+  credit_grant_id: Joi.string().empty(''),
+  start: Joi.number().integer().optional(),
+  end: Joi.number().integer().optional(),
+  source: Joi.string().empty(''),
+});
+
+router.get('/', authMine, async (req, res) => {
+  try {
+    const { page, pageSize, ...query } = await listSchema.validateAsync(req.query, { stripUnknown: true });
+    const where = getWhereFromKvQuery(query.q);
+
+    if (query.customer_id) {
+      where.customer_id = query.customer_id;
+    }
+
+    if (query.subscription_id) {
+      where.subscription_id = query.subscription_id;
+    }
+
+    if (query.credit_grant_id) {
+      where.credit_grant_id = query.credit_grant_id;
+    }
+
+    if (query.source) {
+      where.source = query.source;
+    }
+
+    if (query.start) {
+      where.created_at = {
+        [Op.gte]: new Date(query.start * 1000),
+      };
+    }
+
+    if (query.end) {
+      where.created_at = {
+        [Op.lte]: new Date(query.end * 1000),
+      };
+    }
+
+    const { rows: list, count } = await CreditTransaction.findAndCountAll({
+      where,
+      order: getOrder(query, [['created_at', query.o === 'asc' ? 'ASC' : 'DESC']]),
+      offset: (page - 1) * pageSize,
+      limit: pageSize,
+      include: [
+        {
+          model: Customer,
+          as: 'customer',
+          attributes: ['id', 'name', 'email', 'did'],
+        },
+        {
+          model: Meter,
+          as: 'meter',
+        },
+        {
+          model: Subscription,
+          as: 'subscription',
+          attributes: ['id', 'description', 'status'],
+          required: false,
+        },
+        {
+          model: CreditGrant,
+          as: 'creditGrant',
+          attributes: ['id', 'name'],
+        },
+      ],
+    });
+
+    const paymentCurrencies = await PaymentCurrency.findAll({
+      attributes: ['id', 'symbol', 'decimal', 'maximum_precision'],
+      where: {
+        type: 'credit',
+      },
+    });
+
+    const result = list.map((item) => {
+      return {
+        ...item.toJSON(),
+        // @ts-ignore
+        paymentCurrency: paymentCurrencies.find((x) => x.id === item.meter?.currency_id),
+      };
+    });
+
+    return res.json({ count, list: result, paging: { page, pageSize } });
+  } catch (err) {
+    logger.error('Error listing credit transactions', err);
+    return res.status(400).json({ error: err.message });
+  }
+});
+
+const summarySchema = Joi.object({
+  customer_id: Joi.string().optional(),
+  subscription_id: Joi.string().optional(),
+  currency_id: Joi.string().optional(),
+  start: Joi.number().integer().optional(),
+  end: Joi.number().integer().optional(),
+}).unknown(true);
+
+// get credit transaction summary for customer or subscription
+router.get('/summary', authMine, async (req, res) => {
+  try {
+    const {
+      customer_id: customerId,
+      subscription_id: subscriptionId,
+      currency_id: currencyId,
+      start,
+      end,
+    } = await summarySchema.validateAsync(req.query, { stripUnknown: true });
+
+    const result = await CreditTransaction.getUsageSummary({
+      customerId,
+      subscriptionId,
+      currencyId,
+      startTime: start ? new Date(start * 1000) : undefined,
+      endTime: end ? new Date(end * 1000) : undefined,
+    });
+
+    return res.json(result);
+  } catch (err) {
+    logger.error('get credit transaction summary failed', err);
+    return res.status(400).json({ error: err.message });
+  }
+});
+
+router.get('/:id', authPortal, async (req, res) => {
+  try {
+    const transaction = await CreditTransaction.findByPk(req.params.id, {
+      include: [
+        {
+          model: Customer,
+          as: 'customer',
+          attributes: ['id', 'name', 'email', 'did', 'phone', 'description'],
+        },
+        {
+          model: CreditGrant,
+          as: 'creditGrant',
+          include: [
+            {
+              model: PaymentCurrency,
+              as: 'paymentCurrency',
+            },
+          ],
+        },
+        {
+          model: Meter,
+          as: 'meter',
+          attributes: ['id', 'name', 'event_name', 'unit', 'status', 'description'],
+        },
+        {
+          model: Subscription,
+          as: 'subscription',
+          attributes: [
+            'id',
+            'description',
+            'status',
+            'current_period_start',
+            'current_period_end',
+            'cancel_at_period_end',
+            'canceled_at',
+          ],
+          required: false,
+        },
+      ],
+    });
+
+    if (!transaction) {
+      return res.status(404).json({ error: 'Credit transaction not found' });
+    }
+
+    return res.json(transaction);
+  } catch (err) {
+    logger.error('get credit transaction failed', err);
+    return res.status(400).json({ error: err.message });
+  }
+});
+
+export default router;

package/api/src/routes/index.ts

@@ -2,11 +2,15 @@ import { Router } from 'express';
 
 import { PaymentCurrency } from '../store/models/payment-currency';
 import checkoutSessions from './checkout-sessions';
+import creditGrants from './credit-grants';
+import creditTransactions from './credit-transactions';
 import customers from './customers';
 import donations from './donations';
 import events from './events';
 import stripe from './integrations/stripe';
 import invoices from './invoices';
+import meterEvents from './meter-events';
+import meters from './meters';
 import passports from './passports';
 import paymentCurrencies from './payment-currencies';
 import paymentIntents from './payment-intents';
@@ -48,11 +52,15 @@ router.use(async (req, _, next) => {
 });
 
 router.use('/checkout-sessions', checkoutSessions);
+router.use('/credit-grants', creditGrants);
+router.use('/credit-transactions', creditTransactions);
 router.use('/customers', customers);
 router.use('/donations', donations);
 router.use('/events', events);
 router.use('/invoices', invoices);
 router.use('/integrations/stripe', stripe);
+router.use('/meter-events', meterEvents);
+router.use('/meters', meters);
 router.use('/passports', passports);
 router.use('/payment-intents', paymentIntents);
 router.use('/payment-links', paymentLinks);

package/api/src/routes/meter-events.ts

@@ -0,0 +1,347 @@
+import { Router } from 'express';
+import Joi from 'joi';
+import { Op, QueryTypes } from 'sequelize';
+
+import { fromTokenToUnit } from '@ocap/util';
+import { createListParamSchema, getOrder, getWhereFromKvQuery, MetadataSchema } from '../libs/api';
+import logger from '../libs/logger';
+import { authenticate } from '../libs/security';
+import { formatMetadata } from '../libs/util';
+import { Customer, Meter, MeterEvent, MeterEventStatus, PaymentCurrency, Subscription } from '../store/models';
+
+const router = Router();
+const auth = authenticate<MeterEvent>({ component: true, roles: ['owner', 'admin'] });
+const authMine = authenticate<MeterEvent>({ component: true, roles: ['owner', 'admin'], mine: true });
+
+const meterEventSchema = Joi.object({
+  event_name: Joi.string().max(128).required(),
+  payload: Joi.object({
+    customer_id: Joi.string().required(),
+    value: Joi.number().greater(0).required(),
+    subscription_id: Joi.string().max(128).optional(),
+  }).required(),
+  timestamp: Joi.number().integer().optional(),
+  identifier: Joi.string().max(255).required(),
+  metadata: MetadataSchema,
+});
+
+const listSchema = createListParamSchema<{
+  event_name?: string;
+  meter_id?: string;
+  customer_id?: string;
+  start?: number;
+  end?: number;
+}>({
+  event_name: Joi.string().empty(''),
+  meter_id: Joi.string().empty(''),
+  customer_id: Joi.string().empty(''),
+  start: Joi.number().integer().optional(),
+  end: Joi.number().integer().optional(),
+});
+
+const statsSchema = Joi.object({
+  meter_id: Joi.string().required(),
+  start: Joi.number().integer().required(),
+  end: Joi.number().integer().required(),
+  customer_id: Joi.string().optional(),
+  granularity: Joi.string().valid('minute', 'hour', 'day').default('day'),
+});
+
+router.get('/', authMine, async (req, res) => {
+  try {
+    const { page, pageSize, ...query } = await listSchema.validateAsync(req.query, { stripUnknown: true });
+    const where = getWhereFromKvQuery(query.q);
+
+    if (typeof query.livemode === 'boolean') {
+      where.livemode = query.livemode;
+    }
+    if (query.event_name) {
+      where.event_name = query.event_name;
+    }
+
+    if (query.meter_id) {
+      const meter = await Meter.findByPk(query.meter_id);
+      if (meter) {
+        where.event_name = meter.event_name;
+      }
+    }
+
+    if (query.customer_id) {
+      where['payload.customer_id'] = query.customer_id;
+    }
+
+    if (query.start || query.end) {
+      where.created_at = {};
+      if (query.start) {
+        where.created_at[Op.gte] = new Date(query.start * 1000);
+      }
+      if (query.end) {
+        where.created_at[Op.lte] = new Date(query.end * 1000);
+      }
+    }
+
+    const { rows: list, count } = await MeterEvent.findAndCountAll({
+      where,
+      order: getOrder(query, [['created_at', query.o === 'asc' ? 'ASC' : 'DESC']]),
+      offset: (page - 1) * pageSize,
+      limit: pageSize,
+    });
+    const expanded = await MeterEvent.expand(list, !!req.livemode, {
+      customer: true,
+      subscription: true,
+      meter: !!query.meter_id,
+    });
+
+    res.json({ count, list: expanded, paging: { page, pageSize } });
+  } catch (err) {
+    logger.error('Error listing meter events', err);
+    res.status(400).json({ error: err?.message });
+  }
+});
+
+router.get('/stats', authMine, async (req, res) => {
+  try {
+    const {
+      meter_id: meterId,
+      start,
+      end,
+      customer_id: customerId,
+      granularity,
+    } = await statsSchema.validateAsync(req.query, { stripUnknown: true });
+
+    const meter = await Meter.findByPk(meterId);
+    if (!meter) {
+      return res.status(404).json({ error: 'Meter not found' });
+    }
+
+    const startDate = new Date(start * 1000);
+    const endDate = new Date(end * 1000);
+
+    // 根据granularity选择聚合方式
+    let dateFormat;
+    let groupBy;
+    if (granularity === 'minute') {
+      // 分钟级别聚合（实际按小时聚合，前端处理更细粒度显示）
+      dateFormat = "DATE_FORMAT(created_at, '%Y-%m-%d %H:00:00')";
+      groupBy = "DATE_FORMAT(created_at, '%Y-%m-%d %H')";
+    } else if (granularity === 'hour') {
+      dateFormat = "DATE_FORMAT(created_at, '%Y-%m-%d %H:00:00')";
+      groupBy = "DATE_FORMAT(created_at, '%Y-%m-%d %H')";
+    } else {
+      dateFormat = 'DATE(created_at)';
+      groupBy = 'DATE(created_at)';
+    }
+
+    // 构建查询条件
+    let whereClause =
+      'event_name = :eventName AND livemode = :livemode AND created_at >= :startDate AND created_at <= :endDate';
+    const replacements: any = {
+      eventName: meter.event_name,
+      livemode: !!req.livemode,
+      startDate: startDate.toISOString(),
+      endDate: endDate.toISOString(),
+    };
+
+    if (customerId) {
+      whereClause += " AND payload->>'customer_id' = :customerId";
+      replacements.customerId = customerId;
+    }
+
+    const statsQuery = `
+      SELECT 
+        ${dateFormat} as date,
+        ${dateFormat} as timestamp,
+        COUNT(*) as event_count,
+        COALESCE(SUM(CAST(payload->>'value' AS DECIMAL)), 0) as total_value
+      FROM meter_events 
+      WHERE ${whereClause}
+      GROUP BY ${groupBy}
+      ORDER BY ${groupBy}
+    `;
+
+    const { sequelize } = MeterEvent;
+    if (!sequelize) {
+      return res.status(500).json({ error: 'Database connection not available' });
+    }
+
+    const stats = await sequelize.query(statsQuery, {
+      replacements,
+      type: QueryTypes.SELECT,
+    });
+
+    return res.json({
+      count: stats.length,
+      list: stats.map((item: any) => ({
+        ...item,
+        timestamp: new Date(item.date).toISOString(),
+      })),
+    });
+  } catch (err) {
+    logger.error('Error getting meter event stats', err);
+    return res.status(400).json({ error: err?.message });
+  }
+});
+
+router.post('/', auth, async (req, res) => {
+  try {
+    const { error } = meterEventSchema.validate(req.body);
+    if (error) {
+      return res.status(400).json({ error: `Meter event create request invalid: ${error.message}` });
+    }
+
+    const existing = await MeterEvent.isEventExists(req.body.identifier);
+    if (existing) {
+      return res.status(400).json({ error: `Event with identifier "${req.body.identifier}" already exists` });
+    }
+
+    const meter = await Meter.getMeterByEventName(req.body.event_name, !!req.livemode);
+    if (!meter) {
+      return res
+        .status(400)
+        .json({ error: `Meter not found for event name "${req.body.event_name}"`, code: 'METER_NOT_FOUND' });
+    }
+
+    if (meter.status !== 'active') {
+      return res
+        .status(400)
+        .json({ error: 'Meter is not active, please activate it first.', code: 'METER_NOT_ACTIVE' });
+    }
+
+    const paymentCurrency = await PaymentCurrency.findByPk(meter.currency_id);
+    if (!paymentCurrency) {
+      return res.status(400).json({ error: `Payment currency not found for meter "${meter.id}"` });
+    }
+
+    if (req.body.payload.subscription_id) {
+      const subscription = await Subscription.findByPk(req.body.payload.subscription_id);
+      if (!subscription) {
+        return res.status(400).json({ error: `Subscription not found for meter event "${req.body.event_name}"` });
+      }
+      if (subscription.currency_id !== paymentCurrency.id) {
+        return res.status(400).json({ error: 'Subscription currency does not match meter currency' });
+      }
+      if (!subscription.isConsumesCredit()) {
+        return res.status(400).json({ error: 'Subscription does not consume credit' });
+      }
+      if (subscription.customer_id !== req.body.payload.customer_id) {
+        return res.status(400).json({ error: 'This is not your subscription' });
+      }
+      if (subscription.isImmutable()) {
+        return res.status(400).json({ error: 'Subscription is immutable' });
+      }
+    }
+
+    const customer = await Customer.findByPkOrDid(req.body.payload.customer_id);
+    if (!customer) {
+      return res.status(400).json({ error: 'Customer not found' });
+    }
+
+    const timestamp = req.body.timestamp || req.body.payload.timestamp || Math.floor(Date.now() / 1000);
+
+    const eventData = {
+      event_name: req.body.event_name,
+      payload: {
+        customer_id: customer.id,
+        currency_id: paymentCurrency.id,
+        decimal: paymentCurrency.decimal,
+        unit: paymentCurrency.name,
+        subscription_id: req.body.payload.subscription_id,
+        value: fromTokenToUnit(req.body.payload.value, paymentCurrency.decimal).toString(),
+      },
+      identifier: req.body.identifier,
+      livemode: !!req.livemode,
+      processed: false,
+      status: 'pending' as MeterEventStatus,
+      attempt_count: 0,
+      credit_consumed: '0',
+      credit_pending: fromTokenToUnit(req.body.payload.value, paymentCurrency.decimal).toString(),
+      created_via: req.user?.via || 'api',
+      metadata: formatMetadata(req.body.metadata),
+      timestamp,
+    };
+
+    const event = await MeterEvent.create(eventData);
+
+    logger.info('Meter event created and will be queued for processing via afterCreate hook', {
+      eventId: event.id,
+      eventName: event.event_name,
+    });
+
+    return res.json({
+      ...event.toJSON(),
+      processing: {
+        queued: true,
+        message: 'Credit consumption will be processed asynchronously',
+      },
+    });
+  } catch (err) {
+    logger.error('create meter event failed', { error: err?.message, request: req.body });
+    return res.status(400).json({ error: err?.message });
+  }
+});
+
+router.get('/pending-amount', authMine, async (req, res) => {
+  try {
+    const where: any = {
+      status: 'requires_action',
+      livemode: !!req.livemode,
+    };
+    if (req.query.subscription_id) {
+      where['payload.subscription_id'] = req.query.subscription_id;
+    }
+    if (req.query.customer_id) {
+      where['payload.customer_id'] = req.query.customer_id;
+    }
+    const [summary] = await MeterEvent.getPendingAmounts({
+      subscriptionId: req.query.subscription_id as string,
+      livemode: !!req.livemode,
+      currencyId: req.query.currency_id as string,
+      status: ['requires_action', 'requires_capture'],
+      customerId: req.query.customer_id as string,
+    });
+    return res.json(summary);
+  } catch (err) {
+    logger.error('Error getting meter event pending amount', err);
+    return res.status(400).json({ error: err?.message });
+  }
+});
+router.get('/:id', authMine, async (req, res) => {
+  try {
+    logger.info('get meter event', { id: req.params.id });
+    const event = await MeterEvent.findByPk(req.params.id);
+
+    if (!event) {
+      return res.status(404).json({ error: 'Meter event not found' });
+    }
+
+    const customerId = event.getCustomerId();
+    const subscriptionId = event.getSubscriptionId();
+    const subscription = subscriptionId ? await Subscription.findByPk(subscriptionId) : null;
+    const customer = customerId ? await Customer.findByPk(customerId) : null;
+    if (!customer) {
+      return res.status(404).json({ error: 'Customer not found' });
+    }
+    if (customer.did !== req.user?.did && !['owner', 'admin'].includes(req.user?.role || '')) {
+      return res.status(403).json({ error: 'You are not allowed to access this resource' });
+    }
+    const meter = await Meter.getMeterByEventName(event.event_name, event.livemode);
+    let paymentCurrency = null;
+    if (meter) {
+      paymentCurrency = await PaymentCurrency.findByPk(meter.currency_id);
+    }
+
+    const result = {
+      ...event.toJSON(),
+      customer,
+      subscription,
+      meter,
+      paymentCurrency,
+    };
+    return res.json(result);
+  } catch (err) {
+    logger.error('Error getting meter event', err);
+    return res.status(400).json({ error: err?.message });
+  }
+});
+
+export default router;