payment-kit 1.18.35 → 1.18.36

package/api/src/crons/subscription-trial-will-end.ts

@@ -25,7 +25,7 @@ export class SubscriptionTrialWillEndSchedule extends BaseSubscriptionScheduleNo
         },
         status: 'trialing',
       },
-      attributes: ['id', 'current_period_start', 'current_period_end', 'trial_end'],
+      attributes: ['id', 'current_period_start', 'current_period_end', 'trial_end', 'status'],
       raw: true,
     });
 

package/api/src/index.ts

@@ -43,6 +43,7 @@ import rechargeAccountHandlers from './routes/connect/recharge-account';
 import { initialize } from './store/models';
 import { sequelize } from './store/sequelize';
 import { initUserHandler } from './integrations/blocklet/user';
+import { startUploadBillingInfoListener } from './queues/space';
 
 dotenv.config();
 
@@ -115,6 +116,7 @@ export const server = app.listen(port, (err?: any) => {
   startCheckoutSessionQueue().then(() => logger.info('checkoutSession queue started'));
   startNotificationQueue().then(() => logger.info('notification queue started'));
   startRefundQueue().then(() => logger.info('refund queue started'));
+  startUploadBillingInfoListener();
 
   if (process.env.BLOCKLET_MODE === 'production') {
     ensureWebhookRegistered().catch(console.error);

package/api/src/libs/did-space.ts

@@ -0,0 +1,235 @@
+// eslint-disable-next-line import/no-extraneous-dependencies
+import { SpaceClient, GetObjectCommand, PutObjectCommand } from '@blocklet/did-space-js';
+import { blocklet, wallet } from './auth';
+import logger from './logger';
+import env from './env';
+import { streamToString } from './util';
+
+// Get user's DID Space endpoint
+export const getEndpointAndSpaceDid = async (userDid: string): Promise<{ endpoint: string; spaceDid: string }> => {
+  const { user } = await blocklet.getUser(userDid);
+  if (!user) {
+    throw new Error('User not found');
+  }
+  if (!user.didSpace.endpoint) {
+    throw new Error(`DID Space endpoint is not set for user ${userDid}`);
+  }
+  return {
+    endpoint: user.didSpace.endpoint,
+    spaceDid: user.didSpace.did,
+  };
+};
+
+// Initialize DID Space client
+export const getSpaceClient = async (userDid: string, endpoint?: string) => {
+  let spaceEndpoint = endpoint;
+  if (!spaceEndpoint) {
+    const result = await getEndpointAndSpaceDid(userDid);
+    spaceEndpoint = result.endpoint;
+  }
+  return new SpaceClient({
+    endpoint: spaceEndpoint,
+    wallet,
+  });
+};
+
+// Universal billing information format
+export interface BillingInfo {
+  tx_hash: string; // Transaction hash
+  timestamp: number; // Transaction timestamp
+
+  // Basic billing information
+  invoice_id: string; // Invoice ID
+  category: string; // Bill category
+  description?: string; // Bill description: subscription payment, recharge, refund, etc.
+
+  // Payment information
+  amount: string; // Payment amount
+  currency: {
+    // Payment medium information
+    symbol: string; // Currency symbol
+    decimal: number; // Decimal places
+    type: string; // Payment type (arcblock/ethereum)
+    chain_id: string; // Chain ID
+    explorer_host: string; // Explorer host
+    explorer_tx_url: string; // Explorer transaction URL
+  };
+
+  // Related business information
+  related?: {
+    type: string; // Relation type (subscription/invoice)
+    id: string; // Related entity ID
+    name: string; // Related entity name
+    status?: string; // Related entity status
+    link?: string; // Link to the related entity
+    period_start?: number; // Period start time
+    period_end?: number; // Period end time
+  };
+
+  customer_did: string; // Customer DID
+  tags?: string[]; // User defined tags
+  app_pid: string; // App PID
+  link?: string; // Link to the related entity
+}
+
+// Merge billing information, preserving user customizations
+const mergeBillingInfo = (existing: BillingInfo, updated: Partial<BillingInfo>): BillingInfo => {
+  return {
+    ...(existing || {}),
+    ...updated,
+    // Preserve user customizations if they exist
+    description: existing?.description || updated?.description,
+    category: existing?.category || updated?.category || 'other',
+    tags: Array.from(new Set([...(existing.tags || []), ...(updated.tags || [])])),
+  };
+};
+
+// Upload or update billing information to DID Space
+export const uploadBillingInfo = async (
+  userDid: string,
+  billingInfo: BillingInfo,
+  endpoint?: string
+): Promise<boolean> => {
+  try {
+    // Validate required fields
+    if (!billingInfo.tx_hash || !billingInfo.invoice_id || !billingInfo.amount) {
+      logger.error('Missing required fields in billingInfo');
+      return false;
+    }
+
+    const client = await getSpaceClient(userDid, endpoint);
+
+    const key = `txs/${billingInfo.tx_hash}/metadata.json`;
+
+    let finalBillingInfo = {
+      ...billingInfo,
+      app_pid: billingInfo?.app_pid || env.appPid,
+    };
+
+    // Check existing bill
+    const existingBill = await client.send(new GetObjectCommand({ key }));
+    if (existingBill.statusCode === 200 && existingBill.data) {
+      // Merge with existing data if force update
+      const existing = JSON.parse(await streamToString(existingBill.data)) as BillingInfo;
+      finalBillingInfo = mergeBillingInfo(existing, billingInfo);
+      logger.info('Updating existing billing:', { userDid, txHash: billingInfo.tx_hash });
+    }
+
+    const payload = new PutObjectCommand({
+      key,
+      data: JSON.stringify(finalBillingInfo),
+    });
+
+    const result = await client.send(payload);
+
+    if (result.statusCode !== 200) {
+      logger.error('Upload billing info failed:', result);
+      return false;
+    }
+
+    logger.info(existingBill.statusCode === 200 ? 'Bill updated:' : 'Bill created:', {
+      userDid,
+      txHash: billingInfo.tx_hash,
+    });
+    return true;
+  } catch (error) {
+    logger.error('Upload billing info error:', error);
+    return false;
+  }
+};
+
+// Get specific billing information by transaction hash
+export const getBillingInfo = async (
+  userDid: string,
+  txHash: string,
+  endpoint?: string
+): Promise<BillingInfo | null> => {
+  try {
+    if (!txHash) {
+      logger.error('Transaction hash is required');
+      return null;
+    }
+
+    const client = await getSpaceClient(userDid, endpoint);
+    const payload = new GetObjectCommand({
+      key: `txs/${txHash}/metadata.json`,
+    });
+
+    const result = await client.send(payload);
+
+    if (result.statusCode !== 200 || !result.data) {
+      logger.debug('Bill not found:', { userDid, txHash });
+      return null;
+    }
+
+    const billingInfo = JSON.parse(await streamToString(result.data)) as BillingInfo;
+
+    // Validate parsed data
+    if (!billingInfo.tx_hash || !billingInfo.invoice_id) {
+      logger.error('Invalid billing data structure:', { userDid, txHash });
+      return null;
+    }
+
+    return billingInfo;
+  } catch (error) {
+    logger.error('Get billing info error:', { userDid, txHash, error });
+    return null;
+  }
+};
+
+// Update specific fields of billing information
+export const updateBillingInfo = async (
+  userDid: string,
+  txHash: string,
+  updates: Partial<BillingInfo>,
+  endpoint?: string
+): Promise<boolean> => {
+  try {
+    const existing = await getBillingInfo(userDid, txHash, endpoint);
+    if (!existing) {
+      logger.error('Billing not found for update:', { userDid, txHash });
+      return false;
+    }
+
+    const updated = mergeBillingInfo(existing, updates);
+    if (!updated.tx_hash || !updated.invoice_id || !updated.amount) {
+      logger.error('Invalid billing data structure:', { userDid, txHash });
+      return false;
+    }
+    const result = await uploadBillingInfo(userDid, updated, endpoint);
+    return result;
+  } catch (error) {
+    logger.error('Update billing info error:', { userDid, txHash, error });
+    return false;
+  }
+};
+
+// Batch upload/update billing information
+export const uploadBillingInfoBatch = async (
+  userDid: string,
+  billingInfoList: BillingInfo[],
+  endpoint?: string
+): Promise<boolean[]> => {
+  try {
+    if (!Array.isArray(billingInfoList) || billingInfoList.length === 0) {
+      logger.error('Invalid billingInfoList:', { userDid });
+      return [];
+    }
+
+    // Validate all bills before upload
+    const validBills = billingInfoList.filter((bill) => bill.tx_hash && bill.invoice_id && bill.amount);
+
+    if (validBills.length !== billingInfoList.length) {
+      logger.warn('Some bills are invalid and will be skipped');
+    }
+
+    const results = await Promise.all(
+      validBills.map((billingInfo) => uploadBillingInfo(userDid, billingInfo, endpoint))
+    );
+
+    return results;
+  } catch (error) {
+    logger.error('Batch upload error:', { userDid, error });
+    return [];
+  }
+};

package/api/src/libs/util.ts

@@ -1,5 +1,6 @@
 import crypto from 'crypto';
-
+import { Readable } from 'stream';
+import { buffer } from 'node:stream/consumers';
 import { getUrl } from '@blocklet/sdk/lib/component';
 import env from '@blocklet/sdk/lib/env';
 import { getWalletDid } from '@blocklet/sdk/lib/did';
@@ -93,6 +94,19 @@ export function createCodeGenerator(prefix: string, size: number = 24) {
   return prefix ? () => `${prefix}_${generator()}` : generator;
 }
 
+export function stringToStream(str: string): Readable {
+  const stream = new Readable();
+  stream.push(str);
+  stream.push(null);
+
+  return stream;
+}
+
+export const streamToString = async (stream: any, encoding?: BufferEncoding): Promise<string> => {
+  const data = await buffer(stream);
+  return data.toString(encoding);
+};
+
 // FIXME: merge with old metadata
 export function formatMetadata(metadata?: Record<string, any>): Record<string, any> {
   if (!metadata) {
@@ -545,3 +559,21 @@ export function formatCurrencyInfo(
   }
   return paymentMethod && paymentMethod.type !== 'arcblock' ? `${amountStr} (${paymentMethod.name})` : amountStr;
 }
+
+export function getExplorerTxUrl({
+  explorerHost,
+  txHash,
+  type,
+}: {
+  explorerHost: string;
+  txHash: string;
+  type: LiteralUnion<'ethereum' | 'base' | 'arcblock' | 'bitcoin', string>;
+}) {
+  if (!explorerHost || !txHash) {
+    return '';
+  }
+  if (type === 'arcblock') {
+    return joinURL(explorerHost, '/txs', txHash);
+  }
+  return joinURL(explorerHost, '/tx', txHash);
+}

package/api/src/queues/payment.ts

@@ -175,10 +175,13 @@ export const handlePaymentSucceed = async (
       );
   }
 
-  depositVaultQueue.push({
-    id: `deposit-vault-${paymentIntent.currency_id}`,
-    job: { currencyId: paymentIntent.currency_id },
-  });
+  const exist = await depositVaultQueue.get(`deposit-vault-${paymentIntent.currency_id}`);
+  if (!exist) {
+    depositVaultQueue.push({
+      id: `deposit-vault-${paymentIntent.currency_id}`,
+      job: { currencyId: paymentIntent.currency_id },
+    });
+  }
 
   let invoice;
   if (paymentIntent.invoice_id) {

package/api/src/queues/space.ts

@@ -0,0 +1,661 @@
+import { getUrl } from '@blocklet/sdk';
+import { literal, Op } from 'sequelize';
+import { events } from '../libs/event';
+import logger from '../libs/logger';
+import createQueue from '../libs/queue';
+import { uploadBillingInfo, BillingInfo, getEndpointAndSpaceDid } from '../libs/did-space';
+import {
+  Customer,
+  EVMChainType,
+  Invoice,
+  Job,
+  PaymentCurrency,
+  PaymentIntent,
+  PaymentMethod,
+  PaymentMethodSettings,
+  Refund,
+  Subscription,
+  TInvoiceExpanded,
+  TRefundExpanded,
+} from '../store/models';
+import { CHARGE_SUPPORTED_CHAIN_TYPES } from '../libs/constants';
+import env from '../libs/env';
+import dayjs from '../libs/dayjs';
+import { getExplorerTxUrl } from '../libs/util';
+
+// Types
+export type SpaceUploadType = 'invoice' | 'refund' | 'customer' | 'customerInvoiceChunk' | 'customerRefundChunk';
+export type SpaceUploadData = {
+  invoice: { id: string };
+  refund: { id: string };
+  customer: { id: string };
+  customerInvoiceChunk: {
+    customerId: string;
+    chunkIndex: number;
+    totalChunks: number;
+    ids: string[];
+    processTime: number;
+  };
+  customerRefundChunk: {
+    customerId: string;
+    chunkIndex: number;
+    totalChunks: number;
+    ids: string[];
+    processTime: number;
+  };
+};
+
+export type SpaceUploadJob = {
+  type: SpaceUploadType;
+  data: SpaceUploadData[SpaceUploadType];
+};
+
+// Utility functions
+const categoryMap = {
+  stake: 'stake',
+  slash_stake: 'slashStake',
+  overdraft_protection: 'fee',
+  stake_overdraft_protection: 'stake',
+  recharge: 'recharge',
+  return_stake: 'returnStake',
+} as const;
+
+const getBillingCategory = (billingReason: string): string => {
+  if (
+    billingReason.includes('stake') ||
+    billingReason.includes('recharge') ||
+    billingReason === 'overdraft_protection'
+  ) {
+    return categoryMap[billingReason as keyof typeof categoryMap] || 'payment';
+  }
+  return 'payment';
+};
+
+const createSubscriptionInfo = (subscription: Subscription) => ({
+  type: 'subscription' as const,
+  id: subscription.id,
+  name: subscription.description || subscription.id,
+  status: subscription.status,
+  period_start: subscription.current_period_start,
+  period_end: subscription.current_period_end,
+  link: getUrl(`customer/subscription/${subscription.id}`),
+});
+
+const handleInvoicePaid = async (invoiceId: string) => {
+  const invoice = (await Invoice.findByPk(invoiceId, {
+    include: [
+      {
+        model: Customer,
+        as: 'customer',
+        attributes: ['did'],
+      },
+      {
+        model: PaymentCurrency,
+        as: 'paymentCurrency',
+        attributes: ['symbol', 'decimal'],
+      },
+      {
+        model: PaymentMethod,
+        as: 'paymentMethod',
+        attributes: ['type', 'settings'],
+      },
+      {
+        model: Subscription,
+        as: 'subscription',
+        attributes: ['id', 'description', 'status', 'current_period_start', 'current_period_end'],
+      },
+      {
+        model: PaymentIntent,
+        as: 'paymentIntent',
+      },
+    ],
+  })) as TInvoiceExpanded | null;
+
+  // Validation
+  if (!invoice) {
+    logger.info('Upload invoice skipped because invoice not found:', { invoiceId });
+    return;
+  }
+
+  if (invoice.metadata?.did_space_uploaded) {
+    logger.info('Upload invoice skipped because invoice already uploaded:', { invoiceId });
+    return;
+  }
+
+  const paymentDetails = invoice.paymentIntent?.payment_details || invoice.metadata?.payment_details;
+  if (!paymentDetails) {
+    logger.info('Upload invoice skipped because payment details not found:', { invoiceId });
+    return;
+  }
+
+  if (!CHARGE_SUPPORTED_CHAIN_TYPES.includes(invoice?.paymentMethod?.type)) {
+    logger.info('Upload invoice skipped because payment method is not supported:', {
+      invoiceId,
+      paymentMethod: invoice?.paymentMethod?.type,
+    });
+    return;
+  }
+
+  const txHash = paymentDetails[invoice.paymentMethod?.type].tx_hash;
+  if (!txHash) {
+    logger.info('Upload invoice skipped because tx hash not found:', { invoiceId });
+    return;
+  }
+
+  let spaceDid = null;
+  let endpoint = null;
+  try {
+    const result = await getEndpointAndSpaceDid(invoice.customer?.did);
+    spaceDid = result.spaceDid;
+    endpoint = result.endpoint;
+  } catch (error) {
+    logger.info('Customer space endpoint not available:', {
+      invoiceId,
+      did: invoice.customer?.did,
+      error: (error as Error).message,
+    });
+    return;
+  }
+
+  const methodInfo = (invoice.paymentMethod?.settings as PaymentMethodSettings)?.[
+    invoice.paymentMethod?.type as 'arcblock' | EVMChainType
+  ];
+  // Create billing info
+  const billInfo: BillingInfo = {
+    tx_hash: txHash,
+    timestamp: dayjs(invoice.updated_at).unix(),
+    invoice_id: invoice.id,
+    category: getBillingCategory(invoice.billing_reason),
+    description: invoice.description || 'Payment received',
+    amount: invoice.amount_paid,
+    currency: {
+      symbol: invoice.paymentCurrency?.symbol,
+      decimal: invoice.paymentCurrency?.decimal || 18,
+      type: invoice.paymentMethod?.type || '',
+      chain_id: methodInfo?.chain_id || '',
+      explorer_host: methodInfo?.explorer_host || '',
+      explorer_tx_url: methodInfo?.explorer_host
+        ? getExplorerTxUrl({
+            explorerHost: methodInfo?.explorer_host,
+            txHash,
+            type: invoice.paymentMethod?.type || '',
+          })
+        : '',
+    },
+    customer_did: invoice.customer?.did,
+    link: getUrl(`customer/invoice/${invoice.id}`),
+    app_pid: env.appPid,
+  };
+
+  if (invoice.subscription_id && invoice.subscription) {
+    billInfo.related = createSubscriptionInfo(invoice.subscription as Subscription);
+  }
+
+  // Upload billing info
+  const result = await uploadBillingInfo(invoice.customer?.did, billInfo, endpoint);
+  if (result) {
+    // @ts-ignore
+    await invoice.update({
+      metadata: {
+        ...invoice.metadata,
+        did_space_uploaded: true,
+        did_space: spaceDid,
+      },
+    });
+    logger.info('Successfully uploaded paid invoice:', {
+      invoiceId: invoice.id,
+      txHash,
+      customerDid: invoice.customer?.did,
+    });
+  } else {
+    logger.error('Failed to upload paid invoice:', {
+      invoiceId: invoice.id,
+      txHash,
+      customerDid: invoice.customer?.did,
+    });
+  }
+};
+
+const handleRefundPaid = async (refundId: string) => {
+  const refund = (await Refund.findByPk(refundId, {
+    include: [
+      { model: Customer, as: 'customer', attributes: ['did'] },
+      {
+        model: PaymentMethod,
+        as: 'paymentMethod',
+        attributes: ['type', 'settings'],
+      },
+      {
+        model: PaymentIntent,
+        as: 'paymentIntent',
+      },
+      {
+        model: PaymentCurrency,
+        as: 'paymentCurrency',
+        attributes: ['symbol', 'decimal'],
+      },
+    ],
+  })) as TRefundExpanded | null;
+  if (!refund) {
+    logger.info('Upload refund skipped because refund not found:', { refundId });
+    return;
+  }
+
+  if (refund.metadata?.did_space_uploaded) {
+    logger.info('Upload refund skipped because refund already uploaded:', { refundId });
+    return;
+  }
+
+  if (!CHARGE_SUPPORTED_CHAIN_TYPES.includes(refund.paymentMethod?.type)) {
+    logger.info('Upload refund skipped because payment method is not supported:', {
+      refundId,
+      paymentMethod: refund.paymentMethod?.type,
+    });
+    return;
+  }
+  // @ts-ignore
+  const txHash = refund?.payment_details?.[refund.paymentMethod?.type]?.tx_hash;
+  if (!txHash) {
+    logger.info('Upload refund skipped because tx hash not found:', { refundId });
+    return;
+  }
+
+  let spaceDid = null;
+  let endpoint = null;
+  try {
+    const result = await getEndpointAndSpaceDid(refund.customer?.did);
+    spaceDid = result.spaceDid;
+    endpoint = result.endpoint;
+  } catch (error) {
+    logger.info('Customer space endpoint not available:', {
+      refundId,
+      did: refund.customer?.did,
+      error: (error as Error).message,
+    });
+    return;
+  }
+
+  let invoice = null;
+  if (refund.invoice_id) {
+    invoice = await Invoice.findByPk(refund.invoice_id, {
+      include: [{ model: Customer, as: 'customer', attributes: ['did'] }],
+    });
+  }
+  const methodInfo = (refund.paymentMethod?.settings as PaymentMethodSettings)?.[
+    refund.paymentMethod?.type as 'arcblock' | EVMChainType
+  ];
+  const billInfo: BillingInfo = {
+    tx_hash: txHash,
+    timestamp: dayjs(refund.updated_at).unix(),
+    invoice_id: refund.id,
+    category: 'refund',
+    description: refund.description || 'Refund',
+    amount: refund.amount,
+    currency: {
+      symbol: refund.paymentCurrency?.symbol,
+      decimal: refund.paymentCurrency?.decimal || 18,
+      type: refund.paymentMethod?.type || '',
+      chain_id: methodInfo?.chain_id || '',
+      explorer_host: methodInfo?.explorer_host || '',
+      explorer_tx_url: methodInfo?.explorer_host
+        ? getExplorerTxUrl({
+            explorerHost: methodInfo?.explorer_host,
+            txHash,
+            type: refund.paymentMethod?.type || '',
+          })
+        : '',
+    },
+    customer_did: refund.customer?.did,
+    link: getUrl(`customer/invoice/${refund.invoice_id}`),
+    app_pid: env.appPid,
+  };
+  if (invoice) {
+    billInfo.related = {
+      type: 'invoice',
+      id: invoice.id,
+      name: invoice.description || invoice.id,
+      link: getUrl(`customer/invoice/${invoice.id}`),
+    };
+  }
+
+  const result = await uploadBillingInfo(refund.customer?.did, billInfo, endpoint);
+  if (result) {
+    // @ts-ignore
+    await refund.update({
+      metadata: {
+        ...refund.metadata,
+        did_space_uploaded: true,
+        did_space: spaceDid,
+      },
+    });
+    logger.info('Successfully uploaded paid refund:', {
+      refundId: refund.id,
+      txHash,
+      customerDid: refund.customer?.did,
+    });
+  } else {
+    logger.error('Failed to upload paid refund:', { refundId: refund.id, txHash, customerDid: refund.customer?.did });
+  }
+};
+
+/**
+ * create batch tasks for invoice or refund
+ * @param type 'invoice' | 'refund'
+ * @param customerId customer id
+ * @param records records list
+ * @param now current timestamp
+ * @returns number of new tasks created
+ */
+const createBatchTasks = (
+  type: 'invoice' | 'refund',
+  customerId: string,
+  records: { id: string; created_at?: Date }[],
+  now: number
+): { tasksCreated: number; totalRecords: number } => {
+  if (records.length === 0) {
+    return { tasksCreated: 0, totalRecords: 0 };
+  }
+
+  const recordIds = records.map((record) => record.id);
+  const recordLength = recordIds.length;
+  const batchSize = 30;
+  const chunks = Math.ceil(recordLength / batchSize);
+  let tasksCreated = 0;
+
+  for (let i = 0; i < chunks; i++) {
+    const start = i * batchSize;
+    const end = Math.min(start + batchSize, recordLength);
+    const chunkRecordIds = recordIds.slice(start, end);
+    const processTime = new Date(records?.[start]?.created_at || now).getTime();
+    const chunkId = `space-${customerId}-${type}-chunk-${i}-${processTime}`;
+
+    spaceQueue.push({
+      id: chunkId,
+      job: {
+        type: type === 'invoice' ? 'customerInvoiceChunk' : 'customerRefundChunk',
+        data: {
+          customerId,
+          chunkIndex: i,
+          totalChunks: chunks,
+          ids: chunkRecordIds,
+          processTime,
+        },
+      },
+      delay: 60 * (i + 1), // add 1 minute delay for each chunk
+    });
+
+    tasksCreated++;
+  }
+
+  logger.info(`Created ${type} chunk tasks`, {
+    customerId,
+    chunks,
+    totalRecords: recordLength,
+  });
+
+  return {
+    tasksCreated,
+    totalRecords: recordLength,
+  };
+};
+
+const syncCustomerBillingToSpace = async (customerId: string) => {
+  try {
+    const now = Date.now();
+    const customer = await Customer.findByPkOrDid(customerId);
+    if (!customer) {
+      logger.info('Customer not found:', { customerId });
+      return;
+    }
+
+    try {
+      await getEndpointAndSpaceDid(customer.did);
+    } catch (error) {
+      logger.info('Customer space endpoint not available:', {
+        customerId,
+        did: customer.did,
+        error: (error as Error).message,
+      });
+      return;
+    }
+
+    const validMethods = await PaymentMethod.findAll({
+      where: {
+        type: { [Op.in]: CHARGE_SUPPORTED_CHAIN_TYPES },
+      },
+      attributes: ['id'],
+    });
+
+    if (!validMethods.length) {
+      logger.info('No valid payment methods found', { customerId });
+      return;
+    }
+
+    const validMethodIds = validMethods.map((method) => method.id);
+
+    let invoiceProcessTime = 0;
+    let refundProcessTime = 0;
+    try {
+      // get the latest process time from the queue
+      const [invoiceProcessQueue, refundProcessQueue] = await Promise.all([
+        Job.findOne({
+          where: {
+            queue: 'did-space',
+            id: { [Op.like]: `space-${customerId}-invoice-chunk-%` },
+            cancelled: false,
+          },
+          order: [['created_at', 'DESC']],
+        }),
+        Job.findOne({
+          where: {
+            queue: 'did-space',
+            id: { [Op.like]: `space-${customerId}-refund-chunk-%` },
+            cancelled: false,
+          },
+          order: [['created_at', 'DESC']],
+        }),
+      ]);
+
+      invoiceProcessTime = invoiceProcessQueue?.job?.data?.processTime ?? 0;
+      refundProcessTime = refundProcessQueue?.job?.data?.processTime ?? 0;
+      logger.info('Invoice and refund process time', {
+        customerId,
+        invoiceProcessTime,
+        refundProcessTime,
+      });
+    } catch (error) {
+      logger.error('Failed to get invoice and refund process time', { customerId, error });
+    }
+
+    let [invoices, refunds] = await Promise.all([
+      Invoice.findAll({
+        where: {
+          status: 'paid',
+          'metadata.did_space_uploaded': { [Op.not]: true },
+          customer_id: customer.id,
+          default_payment_method_id: { [Op.in]: validMethodIds },
+          // only process invoices after the latest process time
+          created_at: { [Op.gte]: invoiceProcessTime },
+        },
+        attributes: ['id', 'metadata', 'payment_intent_id', 'created_at'],
+        order: [['created_at', 'DESC']],
+      }),
+      Refund.findAll({
+        where: {
+          status: 'succeeded',
+          'metadata.did_space_uploaded': { [Op.not]: true },
+          customer_id: customer.id,
+          payment_method_id: { [Op.in]: validMethodIds },
+          [Op.and]: [literal('payment_details IS NOT NULL')],
+          // only process refunds after the latest process time
+          created_at: { [Op.gte]: refundProcessTime },
+        },
+        attributes: ['id', 'metadata', 'payment_details', 'created_at'],
+        order: [['created_at', 'DESC']],
+      }),
+    ]);
+
+    invoices = invoices.filter((x) => x.metadata?.payment_details || x.payment_intent_id);
+    refunds = refunds.filter((x) => x.payment_details);
+
+    const invoicesLength = invoices.length;
+    const refundsLength = refunds.length;
+    logger.info('Found records to upload:', {
+      customerId,
+      did: customer.did,
+      invoiceCount: invoicesLength,
+      refundCount: refundsLength,
+    });
+
+    if (invoicesLength === 0 && refundsLength === 0) {
+      logger.info('No records to process', { customerId });
+      return;
+    }
+
+    const invoiceChunks = createBatchTasks('invoice', customerId, invoices, now);
+
+    const refundChunks = createBatchTasks('refund', customerId, refunds, now);
+
+    logger.info('Completed creating all chunk tasks', {
+      customerId,
+      invoiceChunks: invoiceChunks.tasksCreated,
+      refundChunks: refundChunks.tasksCreated,
+      totalRecords: invoicesLength + refundsLength,
+    });
+  } catch (error) {
+    logger.error('Failed to create chunk tasks:', {
+      customerId,
+      error: error instanceof Error ? error.message : String(error),
+    });
+  }
+};
+
+const handleCustomerInvoiceChunk = async (data: SpaceUploadData['customerInvoiceChunk']) => {
+  const { customerId, chunkIndex, totalChunks, ids: invoiceIds } = data;
+
+  logger.info('Processing invoice chunk', {
+    customerId,
+    chunkIndex: chunkIndex + 1,
+    totalChunks,
+    invoiceCount: invoiceIds.length,
+  });
+
+  try {
+    await Promise.all(
+      invoiceIds.map((invoiceId) =>
+        handleInvoicePaid(invoiceId).catch((error) => {
+          logger.error('Failed to process invoice:', {
+            customerId,
+            invoiceId,
+            error: error.message,
+          });
+        })
+      )
+    );
+
+    logger.info('Completed invoice chunk processing', {
+      customerId,
+      chunkIndex: chunkIndex + 1,
+      totalChunks,
+      processedInvoices: invoiceIds.length,
+    });
+  } catch (error) {
+    logger.error('Invoice chunk processing failed:', {
+      customerId,
+      chunkIndex,
+      error: error instanceof Error ? error.message : String(error),
+    });
+  }
+};
+
+const handleCustomerRefundChunk = async (data: SpaceUploadData['customerRefundChunk']) => {
+  const { customerId, chunkIndex, totalChunks, ids: refundIds } = data;
+
+  logger.info('Processing refund chunk', {
+    customerId,
+    chunkIndex: chunkIndex + 1,
+    totalChunks,
+    refundCount: refundIds.length,
+  });
+
+  try {
+    await Promise.all(
+      refundIds.map((refundId) =>
+        handleRefundPaid(refundId).catch((error) => {
+          logger.error('Failed to process refund:', {
+            customerId,
+            refundId,
+            error: error.message,
+          });
+        })
+      )
+    );
+
+    logger.info('Completed refund chunk processing', {
+      customerId,
+      chunkIndex: chunkIndex + 1,
+      totalChunks,
+      processedRefunds: refundIds.length,
+    });
+  } catch (error) {
+    logger.error('Refund chunk processing failed:', {
+      customerId,
+      chunkIndex,
+      error: error instanceof Error ? error.message : String(error),
+    });
+  }
+};
+
+const handlers = {
+  invoice: (data: SpaceUploadData['invoice']) => handleInvoicePaid(data.id),
+  refund: (data: SpaceUploadData['refund']) => handleRefundPaid(data.id),
+  customer: (data: SpaceUploadData['customer']) => syncCustomerBillingToSpace(data.id),
+  customerInvoiceChunk: (data: SpaceUploadData['customerInvoiceChunk']) => handleCustomerInvoiceChunk(data),
+  customerRefundChunk: (data: SpaceUploadData['customerRefundChunk']) => handleCustomerRefundChunk(data),
+};
+
+export const handleSpaceUpload = async (job: SpaceUploadJob) => {
+  logger.info('Starting to handle space upload', job);
+  const handler = handlers[job.type];
+  if (!handler) {
+    logger.error('No handler found for job type', { job });
+    return;
+  }
+  // @ts-ignore
+  await handler(job.data);
+};
+
+export const spaceQueue = createQueue<SpaceUploadJob>({
+  name: 'did-space',
+  onJob: handleSpaceUpload,
+  options: {
+    concurrency: 5,
+    maxRetries: 3,
+    enableScheduledJob: true,
+  },
+});
+
+spaceQueue.on('failed', ({ id, job, error }) => {
+  logger.error('Space upload job failed', { id, job, error });
+});
+
+export const startUploadBillingInfoListener = () => {
+  events.on('invoice.paid', (invoice) => {
+    spaceQueue.push({
+      id: `space-${invoice.id}`,
+      job: {
+        type: 'invoice',
+        data: { id: invoice.id },
+      },
+    });
+  });
+
+  events.on('refund.succeeded', (refund) => {
+    spaceQueue.push({
+      id: `space-${refund.id}`,
+      job: { type: 'refund', data: { id: refund.id } },
+    });
+  });
+
+  logger.info('Space upload listeners started');
+};

package/api/src/queues/subscription.ts

@@ -133,7 +133,7 @@ const doHandleSubscriptionInvoice = async ({
   const usageReportStart = usageStart || start - offset;
   const usageReportEnd = usageEnd || end - offset;
 
-  if (subscription.status !== 'trialing') {
+  if (subscription.status !== 'trialing' && reason !== 'recover') {
     // check if usage report is empty
     const usageReportEmpty = await checkUsageReportEmpty(subscription, usageReportStart, usageReportEnd);
     if (usageReportEmpty) {

package/api/src/routes/customers.ts

@@ -25,6 +25,8 @@ import {
 import { getSubscriptionPaymentAddress, calculateRecommendedRechargeAmount } from '../libs/subscription';
 import { expandLineItems } from '../libs/session';
 import { handleNotificationPreferenceChange } from '../queues/notification';
+import { getEndpointAndSpaceDid } from '../libs/did-space';
+import { spaceQueue } from '../queues/space';
 
 const router = Router();
 const auth = authenticate<Customer>({ component: true, roles: ['owner', 'admin'] });
@@ -172,6 +174,51 @@ router.get('/me', sessionMiddleware(), async (req, res) => {
   }
 });
 
+router.post('/sync-to-space', sessionMiddleware(), async (req, res) => {
+  if (!req.user) {
+    return res.status(403).json({ error: 'Unauthorized' });
+  }
+  try {
+    const userDid = req.user.did;
+    const jobId = `space-${userDid}`;
+    const { endpoint } = await getEndpointAndSpaceDid(userDid);
+    if (endpoint) {
+      const mainTask = await spaceQueue.get(jobId);
+      if (mainTask) {
+        return res.json({
+          success: true,
+          message: 'Billing data sync already in progress',
+        });
+      }
+      spaceQueue.push({
+        id: jobId,
+        job: {
+          type: 'customer',
+          data: {
+            id: userDid,
+          },
+        },
+        delay: 60, // delay 1min
+      });
+      logger.info('Queued billing sync to DID Space for user:', { did: req.user.did });
+
+      return res.json({
+        success: true,
+        message: 'Billing data sync will start soon',
+      });
+    }
+    return res.json({
+      success: false,
+      message: 'No endpoint found for the user',
+    });
+  } catch (error) {
+    return res.json({
+      success: false,
+      message: error.message,
+    });
+  }
+});
+
 // get overdue invoices
 router.get('/:id/overdue/invoices', sessionMiddleware(), async (req, res) => {
   if (!req.user) {

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

@@ -298,7 +298,12 @@ export class Invoice extends Model<InferAttributes<Invoice>, InferCreationAttrib
         'subscription_cancel',
         'subscription',
         'manual',
-        'upcoming'
+        'upcoming',
+        'slash_stake',
+        'stake',
+        'overdraft_protection',
+        'stake_overdraft_protection',
+        'recharge'
       ),
     },
     custom_fields: {
@@ -469,8 +474,12 @@ export class Invoice extends Model<InferAttributes<Invoice>, InferCreationAttrib
         createdAt: 'created_at',
         updatedAt: 'updated_at',
         hooks: {
-          afterCreate: (model: Invoice, options) =>
-            createEvent('Invoice', 'invoice.created', model, options).catch(console.error),
+          afterCreate: (model: Invoice, options) => {
+            createEvent('Invoice', 'invoice.created', model, options).catch(console.error);
+            if (model.status === 'paid') {
+              createEvent('Invoice', 'invoice.paid', model, options).catch(console.error);
+            }
+          },
           afterUpdate: (model: Invoice, options) => {
             createEvent('Invoice', 'invoice.updated', model, options).catch(console.error);
             createStatusEvent(

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

@@ -13,8 +13,14 @@ import {
   getSubscriptionNotificationCustomActions,
   isUserInBlocklist,
   api,
+  md5,
+  safeJsonParse,
+  getExplorerLink,
+  resolveAddressChainTypes,
+  formatCurrencyInfo,
+  getExplorerTxUrl,
 } from '../../src/libs/util';
-import type { Subscription, PaymentMethod } from '../../src/store/models';
+import type { Subscription, PaymentMethod, PaymentCurrency } from '../../src/store/models';
 
 import { blocklet } from '../../src/libs/auth';
 import logger from '../../src/libs/logger';
@@ -653,3 +659,211 @@ describe('isUserInBlocklist', () => {
     expect(result).toBe(true);
   });
 });
+
+describe('md5', () => {
+  it('should generate a consistent hash for the same input', () => {
+    const input = 'test-string';
+    const result1 = md5(input);
+    const result2 = md5(input);
+    expect(result1).toBe(result2);
+  });
+
+  it('should generate different hashes for different inputs', () => {
+    const result1 = md5('test-string-1');
+    const result2 = md5('test-string-2');
+    expect(result1).not.toBe(result2);
+  });
+
+  it('should return a 32 character hexadecimal string', () => {
+    const result = md5('test-string');
+    expect(result).toMatch(/^[0-9a-f]{32}$/);
+  });
+});
+
+describe('safeJsonParse', () => {
+  it('should parse valid JSON strings', () => {
+    const input = '{"key":"value","number":123}';
+    const result = safeJsonParse(input, null);
+    expect(result).toEqual({ key: 'value', number: 123 });
+  });
+
+  it('should return the default value when parsing invalid JSON', () => {
+    const input = '{invalid json}';
+    const defaultValue = { default: true };
+    const result = safeJsonParse(input, defaultValue);
+    expect(result).toEqual(defaultValue);
+  });
+
+  it('should return the input when parsing fails and no default value is provided', () => {
+    const input = '{invalid json}';
+    const result = safeJsonParse(input, undefined);
+    expect(result).toBe(input);
+  });
+});
+
+describe('getExplorerLink', () => {
+  it('should return undefined when chainHost is not provided', () => {
+    const result = getExplorerLink({
+      type: 'asset',
+      did: 'did:example:123',
+      chainHost: undefined,
+    });
+    expect(result).toBeUndefined();
+  });
+
+  it('should construct a proper asset URL with the given parameters', () => {
+    const result = getExplorerLink({
+      type: 'asset',
+      did: 'did:example:123',
+      chainHost: 'https://chain.example.com',
+    });
+    expect(result).toBe('https://chain.example.com/explorer/assets/did:example:123');
+  });
+
+  it('should construct a proper account URL with the given parameters', () => {
+    const result = getExplorerLink({
+      type: 'account',
+      did: 'did:example:123',
+      chainHost: 'https://chain.example.com',
+    });
+    expect(result).toBe('https://chain.example.com/explorer/accounts/did:example:123');
+  });
+
+  it('should append query parameters when provided', () => {
+    const result = getExplorerLink({
+      type: 'tx',
+      did: 'txhash123',
+      chainHost: 'https://chain.example.com',
+      queryParams: { foo: 'bar', baz: 'qux' },
+    });
+    expect(result).toBe('https://chain.example.com/explorer/txs/txhash123?foo=bar&baz=qux');
+  });
+
+  it('should construct a default URL when type is not recognized', () => {
+    const result = getExplorerLink({
+      type: 'unknown',
+      did: 'did:example:123',
+      chainHost: 'https://chain.example.com',
+    });
+    expect(result).toBe('https://chain.example.com/');
+  });
+
+  it('should handle invalid chain host URLs', () => {
+    const result = getExplorerLink({
+      type: 'asset',
+      did: 'did:example:123',
+      chainHost: 'invalid-url',
+    });
+    expect(result).toBeUndefined();
+  });
+});
+
+describe('resolveAddressChainTypes', () => {
+  it('should return ethereum, base, and arcblock for Ethereum addresses', () => {
+    const result = resolveAddressChainTypes('0x71C7656EC7ab88b098defB751B7401B5f6d8976F');
+    expect(result).toEqual(['ethereum', 'base', 'arcblock']);
+  });
+
+  it('should return arcblock for non-Ethereum addresses', () => {
+    const result = resolveAddressChainTypes('did:abt:z1muQ3xqHQK2uiACHyChikobsiY5kLqtShA');
+    expect(result).toEqual(['arcblock']);
+  });
+});
+
+describe('formatCurrencyInfo', () => {
+  it('should format amount with currency symbol when isToken is true', () => {
+    const paymentCurrency = { symbol: 'ETH', decimal: 18 } as PaymentCurrency;
+    const result = formatCurrencyInfo('10', paymentCurrency, null, true);
+    expect(result).toBe('10 ETH');
+  });
+
+  it('should use fromUnitToToken to format amount when isToken is false', () => {
+    const paymentCurrency = { symbol: 'ETH', decimal: 18 } as PaymentCurrency;
+    // Mock the fromUnitToToken function to return a predictable value
+    // In a real test, you might use jest.mock to mock this dependency
+    // For this example, we'll assume fromUnitToToken converts correctly
+    const result = formatCurrencyInfo('1000000000000000000', paymentCurrency, null);
+    // In reality, this would be '1 ETH'
+    expect(result).toContain('ETH');
+  });
+
+  it('should include payment method name for non-arcblock payment methods', () => {
+    const paymentCurrency = { symbol: 'USD', decimal: 2 } as PaymentCurrency;
+    const paymentMethod = { type: 'stripe', name: 'Credit Card' } as PaymentMethod;
+    const result = formatCurrencyInfo('1000', paymentCurrency, paymentMethod, true);
+    expect(result).toBe('1000 USD (Credit Card)');
+  });
+
+  it('should not include payment method name for arcblock payment methods', () => {
+    const paymentCurrency = { symbol: 'ABT', decimal: 18 } as PaymentCurrency;
+    const paymentMethod = { type: 'arcblock', name: 'ArcBlock' } as PaymentMethod;
+    const result = formatCurrencyInfo('5', paymentCurrency, paymentMethod, true);
+    expect(result).toBe('5 ABT');
+  });
+
+  it('should handle undefined or empty amount', () => {
+    const paymentCurrency = { symbol: 'ETH', decimal: 18 } as PaymentCurrency;
+    const result = formatCurrencyInfo('', paymentCurrency, null, true);
+    expect(result).toBe('0 ETH');
+  });
+
+  it('should use default values when currency information is missing', () => {
+    const paymentCurrency = {} as PaymentCurrency;
+    const result = formatCurrencyInfo('10', paymentCurrency, null, true);
+    expect(result).toBe('10 ');
+  });
+});
+
+describe('getExplorerTxUrl', () => {
+  it('should return empty string when explorerHost or txHash is not provided', () => {
+    const result1 = getExplorerTxUrl({
+      explorerHost: '',
+      txHash: 'hash123',
+      type: 'ethereum',
+    });
+    expect(result1).toBe('');
+
+    const result2 = getExplorerTxUrl({
+      explorerHost: 'https://explorer.example.com',
+      txHash: '',
+      type: 'ethereum',
+    });
+    expect(result2).toBe('');
+  });
+
+  it('should construct a proper URL for arcblock type', () => {
+    const result = getExplorerTxUrl({
+      explorerHost: 'https://explorer.example.com',
+      txHash: 'hash123',
+      type: 'arcblock',
+    });
+    expect(result).toBe('https://explorer.example.com/txs/hash123');
+  });
+
+  it('should construct a proper URL for non-arcblock types', () => {
+    const result = getExplorerTxUrl({
+      explorerHost: 'https://explorer.example.com',
+      txHash: 'hash123',
+      type: 'ethereum',
+    });
+    expect(result).toBe('https://explorer.example.com/tx/hash123');
+  });
+
+  it('should handle different blockchain types correctly', () => {
+    const testCases = [
+      { type: 'ethereum', expected: '/tx/' },
+      { type: 'base', expected: '/tx/' },
+      { type: 'bitcoin', expected: '/tx/' },
+      { type: 'arcblock', expected: '/txs/' },
+    ];
+
+    testCases.forEach(({ type, expected }) => {
+      const result = getExplorerTxUrl({
+        explorerHost: 'https://explorer.example.com',
+        txHash: 'hash123',
+        type: type as any,
+      });
+      expect(result).toContain(expected);
+    });
+  });
+});

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.35
+version: 1.18.36
 logo: logo.png
 files:
   - dist
@@ -71,6 +71,7 @@ capabilities:
   navigation: true
   clusterMode: false
   component: true
+  didSpace: requiredOnConnect
 screenshots:
   - setting.png
   - payment.png

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "payment-kit",
-  "version": "1.18.35",
+  "version": "1.18.36",
   "scripts": {
     "dev": "blocklet dev --open",
     "eject": "vite eject",
@@ -47,18 +47,19 @@
     "@abtnode/cron": "^1.16.42",
     "@arcblock/did": "^1.20.2",
     "@arcblock/did-auth-storage-nedb": "^1.7.1",
-    "@arcblock/did-connect": "^2.13.12",
+    "@arcblock/did-connect": "^2.13.13",
     "@arcblock/did-util": "^1.20.2",
     "@arcblock/jwt": "^1.20.2",
-    "@arcblock/ux": "^2.13.12",
+    "@arcblock/ux": "^2.13.13",
     "@arcblock/validator": "^1.20.2",
+    "@blocklet/did-space-js": "^1.0.48",
     "@blocklet/js-sdk": "^1.16.42",
     "@blocklet/logger": "^1.16.42",
-    "@blocklet/payment-react": "1.18.35",
+    "@blocklet/payment-react": "1.18.36",
     "@blocklet/sdk": "^1.16.42",
-    "@blocklet/ui-react": "^2.13.12",
-    "@blocklet/uploader": "^0.1.83",
-    "@blocklet/xss": "^0.1.32",
+    "@blocklet/ui-react": "^2.13.13",
+    "@blocklet/uploader": "^0.1.84",
+    "@blocklet/xss": "^0.1.33",
     "@mui/icons-material": "^5.16.6",
     "@mui/lab": "^5.0.0-alpha.173",
     "@mui/material": "^5.16.6",
@@ -122,7 +123,7 @@
   "devDependencies": {
     "@abtnode/types": "^1.16.42",
     "@arcblock/eslint-config-ts": "^0.3.3",
-    "@blocklet/payment-types": "1.18.35",
+    "@blocklet/payment-types": "1.18.36",
     "@types/cookie-parser": "^1.4.7",
     "@types/cors": "^2.8.17",
     "@types/debug": "^4.1.12",
@@ -168,5 +169,5 @@
       "parser": "typescript"
     }
   },
-  "gitHead": "802a98b5ca81475f8cd7b9dcbb77fce7240b9788"
+  "gitHead": "98872e06bac0c437b53a6648ce4487e9f6d2336b"
 }