payment-kit 1.20.12 → 1.20.14

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

@@ -3,9 +3,18 @@ import Joi from 'joi';
 
 import { Op } from 'sequelize';
 import { createListParamSchema, getOrder, getWhereFromKvQuery } from '../libs/api';
+import { mergePaginate, type DataSource } from '../libs/pagination';
 import logger from '../libs/logger';
 import { authenticate } from '../libs/security';
-import { CreditTransaction, Customer, CreditGrant, Meter, Subscription, PaymentCurrency } from '../store/models';
+import {
+  CreditTransaction,
+  Customer,
+  CreditGrant,
+  Meter,
+  MeterEvent,
+  Subscription,
+  PaymentCurrency,
+} from '../store/models';
 
 const router = Router();
 const authMine = authenticate<CreditTransaction>({ component: true, roles: ['owner', 'admin'], mine: true });
@@ -27,6 +36,7 @@ const listSchema = createListParamSchema<{
   start?: number;
   end?: number;
   source?: string;
+  include_grants?: boolean;
 }>({
   customer_id: Joi.string().empty(''),
   subscription_id: Joi.string().empty(''),
@@ -35,11 +45,13 @@ const listSchema = createListParamSchema<{
   start: Joi.number().integer().optional(),
   end: Joi.number().integer().optional(),
   source: Joi.string().empty(''),
+  include_grants: Joi.boolean().optional(),
 });
 
 router.get('/', authMine, async (req, res) => {
   try {
     const { page, pageSize, ...query } = await listSchema.validateAsync(req.query, { stripUnknown: true });
+    const includeGrants = !!query.include_grants;
     const where = getWhereFromKvQuery(query.q);
 
     if (query.meter_id) {
@@ -73,6 +85,124 @@ router.get('/', authMine, async (req, res) => {
       };
     }
 
+    if (query.start && query.end) {
+      where.created_at = {
+        [Op.between]: [new Date(query.start * 1000), new Date(query.end * 1000)],
+      };
+    }
+
+    if (includeGrants) {
+      if (!query.customer_id) {
+        return res.status(400).json({
+          error: 'customer_id is required when include_grants=true',
+        });
+      }
+
+      const orderDirection = query.o === 'asc' ? 'ASC' : 'DESC';
+
+      const transactionSource: DataSource<any> = {
+        async count() {
+          const count = await CreditTransaction.count({ where });
+          return count;
+        },
+        async fetch(limit, offset) {
+          const rows = await CreditTransaction.findAll({
+            where,
+            limit,
+            offset,
+            order: [['created_at', orderDirection]],
+            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', 'currency_id'] },
+              { model: MeterEvent, as: 'meterEvent', attributes: ['id', 'source_data'], required: false },
+            ],
+          });
+          // Transform transactions
+          return rows.map((item: any) => ({
+            ...item.toJSON(),
+            activity_type: 'transaction',
+          }));
+        },
+        meta: { type: 'database' },
+      };
+
+      // Grant where conditions
+      const grantWhere: any = {
+        customer_id: query.customer_id,
+        status: ['granted', 'depleted'],
+      };
+      if (query.start) {
+        grantWhere.created_at = {
+          [Op.gte]: new Date(query.start * 1000),
+        };
+      }
+      if (typeof query.livemode === 'boolean') grantWhere.livemode = query.livemode;
+
+      const grantSource: DataSource<any> = {
+        async count() {
+          const { count } = await CreditGrant.findAndCountAll({ where: grantWhere });
+          return count;
+        },
+        async fetch(limit, offset) {
+          const { rows } = await CreditGrant.findAndCountAll({
+            where: grantWhere,
+            limit,
+            offset,
+            order: [['created_at', orderDirection]],
+            include: [
+              { model: Customer, as: 'customer', attributes: ['id', 'name', 'email', 'did'] },
+              {
+                model: PaymentCurrency,
+                as: 'paymentCurrency',
+                attributes: ['id', 'symbol', 'decimal', 'maximum_precision'],
+              },
+            ],
+          });
+          // Transform grants
+          return rows.map((item: any) => ({
+            ...item.toJSON(),
+            activity_type: 'grant',
+          }));
+        },
+        meta: { type: 'database' },
+      };
+
+      // Define sort function
+      const sortFn = (a: any, b: any) => {
+        const aDate = new Date(a.created_at).getTime();
+        const bDate = new Date(b.created_at).getTime();
+        return query.o === 'asc' ? aDate - bDate : bDate - aDate;
+      };
+
+      // Use mergePaginate
+      const result = await mergePaginate([transactionSource, grantSource], { page, pageSize }, sortFn);
+
+      // Load payment currencies for final result
+      const paymentCurrencies = await PaymentCurrency.findAll({
+        attributes: ['id', 'symbol', 'decimal', 'maximum_precision'],
+        where: { type: 'credit' },
+      });
+
+      const enhancedData = result.data.map((item) => ({
+        ...item,
+        paymentCurrency: paymentCurrencies.find(
+          (x) => x.id === (item.activity_type === 'grant' ? item.currency_id : item.creditGrant?.currency_id)
+        ),
+      }));
+
+      return res.json({
+        count: result.total,
+        list: enhancedData,
+        paging: result.paging,
+        meta: {
+          unified_cash_flow: true,
+          includes: ['transaction', 'grant'],
+        },
+      });
+    }
+
     const { rows: list, count } = await CreditTransaction.findAndCountAll({
       where,
       order: getOrder(query, [['created_at', query.o === 'asc' ? 'ASC' : 'DESC']]),
@@ -97,27 +227,37 @@ router.get('/', authMine, async (req, res) => {
         {
           model: CreditGrant,
           as: 'creditGrant',
-          attributes: ['id', 'name'],
+          attributes: ['id', 'name', 'currency_id'],
+        },
+        {
+          model: MeterEvent,
+          as: 'meterEvent',
+          attributes: ['id', 'source_data'], // Get source_data from related MeterEvent
+          required: false,
         },
       ],
     });
 
     const paymentCurrencies = await PaymentCurrency.findAll({
       attributes: ['id', 'symbol', 'decimal', 'maximum_precision'],
-      where: {
-        type: 'credit',
-      },
+      where: { type: 'credit' },
     });
 
-    const result = list.map((item) => {
-      return {
-        ...item.toJSON(),
-        // @ts-ignore
-        paymentCurrency: paymentCurrencies.find((x) => x.id === item.meter?.currency_id),
-      };
-    });
+    const result = list.map((item) => ({
+      ...item.toJSON(),
+      activity_type: 'transaction',
+      paymentCurrency: paymentCurrencies.find((x) => x.id === (item as any).creditGrant?.currency_id),
+    }));
 
-    return res.json({ count, list: result, paging: { page, pageSize } });
+    return res.json({
+      count,
+      list: result,
+      paging: { page, pageSize },
+      meta: {
+        unified_cash_flow: false,
+        includes: ['transaction'],
+      },
+    });
   } catch (err) {
     logger.error('Error listing credit transactions', err);
     return res.status(400).json({ error: err.message });

package/api/src/routes/invoices.ts

@@ -23,7 +23,15 @@ import { Price } from '../store/models/price';
 import { Product } from '../store/models/product';
 import { Subscription } from '../store/models/subscription';
 import { getReturnStakeInvoices, getStakingInvoices, retryUncollectibleInvoices } from '../libs/invoice';
-import { CheckoutSession, PaymentLink, TInvoiceExpanded, Discount, Coupon, PromotionCode } from '../store/models';
+import {
+  CheckoutSession,
+  PaymentLink,
+  TInvoiceExpanded,
+  Discount,
+  Coupon,
+  PromotionCode,
+  CreditGrant,
+} from '../store/models';
 import { mergePaginate, defaultTimeOrderBy, getCachedOrFetch, DataSource } from '../libs/pagination';
 import logger from '../libs/logger';
 import { returnOverdraftProtectionQueue, returnStakeQueue } from '../queues/subscription';
@@ -678,6 +686,30 @@ router.get('/:id', authPortal, async (req, res) => {
         }
       }
 
+      let relatedCreditGrants: any[] = [];
+      try {
+        relatedCreditGrants = await CreditGrant.findAll({
+          where: {
+            customer_id: doc.customer_id,
+            'metadata.invoice_id': doc.id,
+          } as any,
+          include: [
+            {
+              model: PaymentCurrency,
+              as: 'paymentCurrency',
+              attributes: ['id', 'symbol', 'decimal', 'name', 'type'],
+            },
+          ],
+          order: [['created_at', 'DESC']],
+        });
+      } catch (error) {
+        logger.error('Failed to fetch related credit grants', {
+          error,
+          invoiceId: doc.id,
+          customerId: doc.customer_id,
+        });
+      }
+
       if (doc.metadata?.invoice_id || doc.metadata?.prev_invoice_id) {
         const relatedInvoice = await Invoice.findByPk(doc.metadata.invoice_id || doc.metadata.prev_invoice_id, {
           attributes: ['id', 'number', 'status', 'billing_reason'],
@@ -686,6 +718,7 @@ router.get('/:id', authPortal, async (req, res) => {
           ...json,
           discountDetails,
           relatedInvoice,
+          relatedCreditGrants,
           paymentLink,
           checkoutSession,
         });
@@ -693,6 +726,7 @@ router.get('/:id', authPortal, async (req, res) => {
       return res.json({
         ...json,
         discountDetails,
+        relatedCreditGrants,
         paymentLink,
         checkoutSession,
       });

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

@@ -14,6 +14,32 @@ const router = Router();
 const auth = authenticate<MeterEvent>({ component: true, roles: ['owner', 'admin'] });
 const authMine = authenticate<MeterEvent>({ component: true, roles: ['owner', 'admin'], mine: true });
 
+const SourceDataSchema = Joi.alternatives()
+  .try(
+    Joi.object().pattern(Joi.string().max(40), Joi.string().max(256).allow('')).min(0),
+    Joi.array()
+      .items(
+        Joi.object({
+          key: Joi.string().max(40).required(),
+          label: Joi.alternatives()
+            .try(
+              Joi.string().max(100),
+              Joi.object({
+                zh: Joi.string().max(100).optional(),
+                en: Joi.string().max(100).optional(),
+              })
+            )
+            .required(),
+          value: Joi.string().max(256).allow('').optional(),
+          type: Joi.string().valid('text', 'image', 'url').optional(),
+          url: Joi.string().uri().optional(),
+          group: Joi.string().max(40).optional(),
+        })
+      )
+      .min(0)
+  )
+  .optional();
+
 const meterEventSchema = Joi.object({
   event_name: Joi.string().max(128).required(),
   payload: Joi.object({
@@ -24,6 +50,7 @@ const meterEventSchema = Joi.object({
   timestamp: Joi.number().integer().optional(),
   identifier: Joi.string().max(255).required(),
   metadata: MetadataSchema,
+  source_data: SourceDataSchema,
 });
 
 const listSchema = createListParamSchema<{
@@ -72,12 +99,12 @@ router.get('/', authMine, async (req, res) => {
     }
 
     if (query.start || query.end) {
-      where.created_at = {};
+      where.timestamp = {};
       if (query.start) {
-        where.created_at[Op.gte] = new Date(query.start * 1000);
+        where.timestamp[Op.gte] = Number(query.start);
       }
       if (query.end) {
-        where.created_at[Op.lte] = new Date(query.end * 1000);
+        where.timestamp[Op.lte] = Number(query.end);
       }
     }
 
@@ -259,6 +286,7 @@ router.post('/', auth, async (req, res) => {
       credit_pending: fromTokenToUnit(value, paymentCurrency.decimal).toString(),
       created_via: req.user?.via || 'api',
       metadata: formatMetadata(req.body.metadata),
+      source_data: req.body.source_data,
       timestamp,
     };
 

package/api/src/routes/meters.ts

@@ -156,6 +156,10 @@ router.put('/:id', auth, async (req, res) => {
     };
 
     if (req.body.metadata) {
+      const { error: metadataError } = MetadataSchema.validate(req.body.metadata);
+      if (metadataError) {
+        return res.status(400).json({ error: `metadata invalid: ${metadataError.message}` });
+      }
       updateData.metadata = formatMetadata(req.body.metadata);
     }
 

package/api/src/routes/payment-currencies.ts

@@ -19,6 +19,7 @@ import { depositVaultQueue } from '../queues/payment';
 import { checkDepositVaultAmount } from '../libs/payment';
 import { getTokenSummaryByDid } from '../integrations/arcblock/stake';
 import { createPaymentLink } from './payment-links';
+import { MetadataSchema } from '../libs/api';
 
 const router = Router();
 
@@ -311,7 +312,7 @@ const updateCurrencySchema = Joi.object({
   name: Joi.string().empty('').max(32).optional(),
   description: Joi.string().empty('').max(255).optional(),
   logo: Joi.string().empty('').optional(),
-  metadata: Joi.object().optional(),
+  metadata: MetadataSchema,
   symbol: Joi.string().empty('').optional(),
 }).unknown(true);
 router.put('/:id', auth, async (req, res) => {

package/api/src/routes/promotion-codes.ts

@@ -8,7 +8,7 @@ import { createIdGenerator, formatMetadata } from '../libs/util';
 import { authenticate } from '../libs/security';
 import { PromotionCode, Coupon, PaymentCurrency } from '../store/models';
 import { getRedemptionData } from '../libs/discount/redemption';
-import { createListParamSchema } from '../libs/api';
+import { createListParamSchema, MetadataSchema } from '../libs/api';
 import logger from '../libs/logger';
 
 const router = Router();
@@ -249,7 +249,7 @@ router.put('/:id', authAdmin, async (req, res) => {
         minimum_amount: Joi.number().positive().optional(),
         minimum_amount_currency: Joi.string().optional(),
       }).optional(),
-      metadata: Joi.object().optional(),
+      metadata: MetadataSchema,
     });
 
     const { error, value } = schema.validate(req.body, {

package/api/src/routes/subscription-items.ts

@@ -139,6 +139,10 @@ router.put('/:id', auth, async (req, res) => {
   }
 
   if (updates.metadata) {
+    const { error: metadataError } = MetadataSchema.validate(updates.metadata);
+    if (metadataError) {
+      return res.status(400).json({ error: `metadata invalid: ${metadataError.message}` });
+    }
     updates.metadata = formatMetadata(updates.metadata);
   }
 

package/api/src/routes/vendor.ts

@@ -1,7 +1,8 @@
+import { getUrl } from '@blocklet/sdk/lib/component';
 import { Router } from 'express';
 import Joi from 'joi';
 
-import { VendorAuth } from '@blocklet/payment-vendor';
+import { Auth as VendorAuth, middleware } from '@blocklet/payment-vendor';
 import { joinURL } from 'ufo';
 import { MetadataSchema } from '../libs/api';
 import { wallet } from '../libs/auth';
@@ -9,7 +10,8 @@ import dayjs from '../libs/dayjs';
 import logger from '../libs/logger';
 import { authenticate } from '../libs/security';
 import { formatToShortUrl } from '../libs/url';
-import { CheckoutSession } from '../store/models';
+import { getBlockletJson } from '../libs/util';
+import { CheckoutSession, Invoice, Subscription } from '../store/models';
 import { ProductVendor } from '../store/models/product-vendor';
 
 const authAdmin = authenticate<CheckoutSession>({ component: true, roles: ['owner', 'admin'] });
@@ -159,6 +161,8 @@ async function createVendor(req: any, res: any) {
       return res.status(400).json({ error: 'Vendor key already exists' });
     }
 
+    const blockletJson = await getBlockletJson(appUrl);
+
     const vendor = await ProductVendor.create({
       vendor_key: vendorKey,
       vendor_type: vendorType || 'launcher',
@@ -170,6 +174,10 @@ async function createVendor(req: any, res: any) {
       app_pid: appPid,
       app_logo: appLogo,
       metadata: metadata || {},
+      extends: {
+        appId: blockletJson?.appId,
+        appPk: blockletJson?.appPk,
+      },
       created_by: req.user?.did || 'admin',
     });
 
@@ -210,6 +218,8 @@ async function updateVendor(req: any, res: any) {
       app_logo: appLogo,
     } = value;
 
+    const blockletJson = await getBlockletJson(appUrl);
+
     if (req.body.vendorKey && req.body.vendorKey !== vendor.vendor_key) {
       const existingVendor = await ProductVendor.findOne({
         where: { vendor_key: req.body.vendorKey },
@@ -229,6 +239,10 @@ async function updateVendor(req: any, res: any) {
       app_pid: appPid,
       app_logo: appLogo,
       vendor_key: req.body.vendor_key,
+      extends: {
+        appId: blockletJson?.appId,
+        appPk: blockletJson?.appPk,
+      },
     };
 
     await vendor.update(Object.fromEntries(Object.entries(updates).filter(([, v]) => v !== undefined)));
@@ -362,9 +376,23 @@ async function getVendorStatus(sessionId: string, isDetail = false) {
     return getVendorStatusByVendorId(item.vendor_id, item.order_id, isDetail);
   });
 
+  const subscriptionId = doc.subscription_id;
+  let shortSubscriptionUrl = '';
+
+  if (isDetail && subscriptionId) {
+    const subscriptionUrl = getUrl(`/customer/subscription/${subscriptionId}`);
+
+    shortSubscriptionUrl = await formatToShortUrl({
+      url: subscriptionUrl,
+      maxVisits: 5,
+      validUntil: dayjs().add(20, 'minutes').format('YYYY-MM-DDTHH:mm:ss+00:00'),
+    });
+  }
+
   return {
     payment_status: doc.payment_status,
     session_status: doc.status,
+    subscriptionUrl: shortSubscriptionUrl,
     vendors: await Promise.all(vendors),
     error: null,
   };
@@ -443,12 +471,71 @@ async function redirectToVendor(req: any, res: any) {
   }
 }
 
+async function getVendorSubscription(req: any, res: any) {
+  const { sessionId } = req.params;
+
+  const checkoutSession = await CheckoutSession.findByPk(sessionId);
+
+  if (!checkoutSession) {
+    return res.status(404).json({ error: 'Checkout session not found' });
+  }
+
+  const subscription = await Subscription.findByPk(checkoutSession.subscription_id);
+
+  if (!subscription) {
+    return res.status(404).json({ error: 'Subscription not found' });
+  }
+
+  const invoices = await Invoice.findAll({
+    where: { subscription_id: subscription.id },
+    order: [['created_at', 'DESC']],
+    attributes: [
+      'id',
+      'amount_due',
+      'amount_paid',
+      'amount_remaining',
+      'status',
+      'currency_id',
+      'period_start',
+      'period_end',
+      'created_at',
+      'due_date',
+      'description',
+      'invoice_pdf',
+    ],
+    limit: 20,
+  });
+
+  return res.json({
+    subscription: subscription.toJSON(),
+    billing_history: invoices,
+  });
+}
+
+async function handleSubscriptionRedirect(req: any, res: any) {
+  const { sessionId } = req.params;
+
+  const checkoutSession = await CheckoutSession.findByPk(sessionId);
+  if (!checkoutSession) {
+    return res.status(404).json({ error: 'Checkout session not found' });
+  }
+
+  return res.redirect(getUrl(`/customer/subscription/${checkoutSession.subscription_id}`));
+}
+
 const router = Router();
 
+const ensureVendorAuth = middleware.ensureVendorAuth((vendorPk: string) =>
+  ProductVendor.findOne({ where: { 'extends.appPk': vendorPk } }).then((v) => v as any)
+);
+
 // FIXME: Authentication not yet added, awaiting implementation @Pengfei
 router.get('/order/:sessionId/status', validateParams(sessionIdParamSchema), getVendorFulfillmentStatus);
 router.get('/order/:sessionId/detail', validateParams(sessionIdParamSchema), getVendorFulfillmentDetail);
 
+router.get('/subscription/:sessionId/redirect', handleSubscriptionRedirect);
+router.get('/subscription/:sessionId', ensureVendorAuth, getVendorSubscription);
+
 router.get(
   '/open/:subscriptionId',
   authAdmin,

package/api/src/routes/webhook-endpoints.ts

@@ -100,6 +100,10 @@ router.put('/:id', auth, async (req, res) => {
     'enabled_events',
   ]);
   if (updates.metadata) {
+    const { error: metadataError } = MetadataSchema.validate(updates.metadata);
+    if (metadataError) {
+      return res.status(400).json({ error: `metadata invalid: ${metadataError.message}` });
+    }
     updates.metadata = formatMetadata(updates.metadata);
   }
 

package/api/src/store/migrations/20250918-add-vendor-extends.ts

@@ -0,0 +1,20 @@
+import { safeApplyColumnChanges, type Migration } from '../migrate';
+
+export const up: Migration = async ({ context }) => {
+  // Add extends column to product_vendors table
+  await safeApplyColumnChanges(context, {
+    product_vendors: [
+      {
+        name: 'extends',
+        field: {
+          type: 'JSON',
+          allowNull: true,
+        },
+      },
+    ],
+  });
+};
+
+export const down: Migration = async ({ context }) => {
+  await context.removeColumn('product_vendors', 'extends');
+};

package/api/src/store/migrations/20250919-add-source-data.ts

@@ -0,0 +1,20 @@
+import { DataTypes } from 'sequelize';
+import { Migration, safeApplyColumnChanges } from '../migrate';
+
+export const up: Migration = async ({ context }) => {
+  await safeApplyColumnChanges(context, {
+    meter_events: [
+      {
+        name: 'source_data',
+        field: {
+          type: DataTypes.JSON,
+          allowNull: true,
+        },
+      },
+    ],
+  });
+};
+
+export const down: Migration = async ({ context }) => {
+  await context.removeColumn('meter_events', 'source_data');
+};

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

@@ -212,7 +212,9 @@ export class CheckoutSession extends Model<InferAttributes<CheckoutSession>, Inf
     | 'cancelled'
     | 'max_retries_exceeded'
     | 'return_requested'
-    | 'sent',
+    | 'sent'
+    | 'returning'
+    | 'returned',
     string
   >;
   declare vendor_info?: Array<{
@@ -227,7 +229,8 @@ export class CheckoutSession extends Model<InferAttributes<CheckoutSession>, Inf
       | 'cancelled'
       | 'max_retries_exceeded'
       | 'return_requested'
-      | 'sent';
+      | 'sent'
+      | 'returned';
     service_url?: string;
     app_url?: string;
     error_message?: string;

package/api/src/store/models/credit-transaction.ts

@@ -135,6 +135,11 @@ export class CreditTransaction extends Model<
       foreignKey: 'subscription_id',
       as: 'subscription',
     });
+
+    this.belongsTo(models.MeterEvent, {
+      foreignKey: 'source',
+      as: 'meterEvent',
+    });
   }
 
   public static async getUsageSummary({