payment-kit 1.27.2 → 1.29.0

package/api/src/libs/error.ts

@@ -2,6 +2,8 @@
 export default class CustomError extends Error {
   code: string;
 
+  details?: Record<string, unknown>;
+
   constructor(code = 'GENERIC', ...params: any[]) {
     super(...params);
 
@@ -11,6 +13,19 @@ export default class CustomError extends Error {
 
     this.code = code;
   }
+
+  withDetails(details: Record<string, unknown>) {
+    this.details = details;
+    return this;
+  }
+
+  toJSON() {
+    return {
+      code: this.code,
+      message: this.message,
+      details: this.details,
+    };
+  }
 }
 
 /**

package/api/src/libs/event.ts

@@ -9,7 +9,48 @@ interface MyEventType extends EventEmitter {
   emit(eventName: LiteralUnion<EventType, string | symbol>, ...args: any[]): boolean;
 }
 
-export const events = new EventEmitter() as MyEventType;
+// eslint-disable-next-line @typescript-eslint/naming-convention
+const _events = new EventEmitter();
+
+// Wrap on/once so async listeners auto-register their Promises in CF Workers.
+// EventEmitter.emit() is synchronous and discards async listener return values.
+// In CF Workers, untracked Promises are abandoned when the request/consumer ends.
+// This wrapper ensures async listener work completes via flushPendingJobs().
+// In Blocklet Server (__cfPendingJobs__ doesn't exist), this is a transparent pass-through.
+function wrapAsyncListener(listener: (...args: any[]) => any): (...args: any[]) => any {
+  return function (...args: any[]) {
+    const result = listener(...args);
+    if (result && typeof result.then === 'function') {
+      // Context-aware: HTTP uses waitUntil (non-blocking), queue/cron uses pendingJobs (blocking)
+      const isHttp = (globalThis as any).__cfHttpContext__;
+      if (isHttp) {
+        const waitUntil = (globalThis as any).__cfWaitUntil__;
+        if (typeof waitUntil === 'function') {
+          waitUntil(result.catch((err: any) => console.error('[event] async listener error:', err?.message || err)));
+        }
+      } else {
+        const pending = (globalThis as any).__cfPendingJobs__;
+        if (Array.isArray(pending)) {
+          pending.push(result.catch((err: any) => console.error('[event] async listener error:', err?.message || err)));
+        }
+      }
+    }
+    return result;
+  };
+}
+
+// eslint-disable-next-line @typescript-eslint/naming-convention
+const _origOn = _events.on.bind(_events);
+// eslint-disable-next-line @typescript-eslint/naming-convention
+const _origOnce = _events.once.bind(_events);
+_events.on = function (eventName: string | symbol, listener: (...args: any[]) => void) {
+  return _origOn(eventName, wrapAsyncListener(listener));
+};
+_events.once = function (eventName: string | symbol, listener: (...args: any[]) => void) {
+  return _origOnce(eventName, wrapAsyncListener(listener));
+};
+
+export const events = _events as MyEventType;
 
 export const emitAsync = (event: string, ...args: any[]) => {
   return new Promise((resolve, reject) => {

package/api/src/libs/invoice.ts

@@ -4,7 +4,8 @@ import { withQuery } from 'ufo';
 
 import { BN, fromUnitToToken } from '@ocap/util';
 import { Op, type WhereOptions } from 'sequelize';
-import { cloneDeep, pick } from 'lodash';
+import cloneDeep from 'lodash/cloneDeep';
+import pick from 'lodash/pick';
 import {
   Customer,
   Invoice,
@@ -78,8 +79,10 @@ export async function getOneTimeProductInfo(invoiceId: string, paymentCurrency:
       throw new Error(`Invoice not found: ${invoiceId}`);
     }
     const json = doc.toJSON();
-    const products = (await Product.findAll()).map((x) => x.toJSON());
-    const prices = (await Price.findAll()).map((x) => x.toJSON());
+    const [products, prices] = await Promise.all([
+      Product.findAll().then((xs) => xs.map((x) => x.toJSON())),
+      Price.findAll().then((xs) => xs.map((x) => x.toJSON())),
+    ]);
     // @ts-ignore
     expandLineItems(json.lines, products, prices);
     const oneTimePaymentInfo: Array<{
@@ -108,12 +111,18 @@ export async function getOneTimeProductInfo(invoiceId: string, paymentCurrency:
 
 export async function getInvoiceShouldPayTotal(invoice: Invoice) {
   try {
-    const subscription = await Subscription.findByPk(invoice.subscription_id);
+    // Parallel fetch: subscription + paymentCurrency are independent;
+    // subscriptionItems + invoiceItems are also independent of each other.
+    const [subscription, paymentCurrency, subscriptionItems, invoiceItems] = await Promise.all([
+      Subscription.findByPk(invoice.subscription_id),
+      PaymentCurrency.findByPk(invoice.currency_id),
+      SubscriptionItem.findAll({ where: { subscription_id: invoice.subscription_id } }),
+      InvoiceItem.findAll({ where: { invoice_id: invoice.id } }),
+    ]);
+
     if (!subscription) {
       throw new Error(`Subscription not found: ${invoice.subscription_id}`);
     }
-
-    const paymentCurrency = await PaymentCurrency.findByPk(invoice.currency_id);
     if (!paymentCurrency) {
       throw new Error(`Payment currency not found: ${invoice.currency_id}`);
     }
@@ -123,12 +132,6 @@ export async function getInvoiceShouldPayTotal(invoice: Invoice) {
       throw new Error(`Payment method not found: ${paymentCurrency.payment_method_id}`);
     }
 
-    const subscriptionItems = await SubscriptionItem.findAll({
-      where: { subscription_id: subscription.id },
-    });
-    const invoiceItems = await InvoiceItem.findAll({
-      where: { invoice_id: invoice.id },
-    });
     const invoiceQuoteIds = invoiceItems
       .map((item) => item.metadata?.quote_id)
       .filter((id): id is string => typeof id === 'string' && id.length > 0);
@@ -577,25 +580,50 @@ async function createInvoiceWithItems(props: BaseInvoiceProps): Promise<{
       })
     : itemsData;
 
+  // Pre-fetch all prices and products in bulk to avoid N+1 queries per item
+  // eslint-disable-next-line @typescript-eslint/naming-convention
+  const _itemPriceIds = enrichedItemsData.map((item) => item.price_id).filter(Boolean);
+  // eslint-disable-next-line @typescript-eslint/naming-convention
+  const [_allPrices, _taxRateForCustomer] = await Promise.all([
+    Price.findAll({ where: { id: _itemPriceIds }, include: [{ model: Product, as: 'product' }] }),
+    // Tax rate matching only depends on customer address — same for all items
+    customer.address?.country
+      ? TaxRate.findMatchingRate({
+          country: customer.address.country,
+          state: customer.address.state,
+          postalCode: customer.address.postal_code,
+          livemode,
+        }).catch(() => null)
+      : Promise.resolve(null),
+  ]);
+  // eslint-disable-next-line @typescript-eslint/naming-convention
+  const _priceMap = new Map(_allPrices.map((p: any) => [p.id, p]));
+
   // create invoice items
   const items = await Promise.all(
     enrichedItemsData.map(async (item) => {
-      // Match tax rate for this specific item
+      // Use pre-fetched price/product for tax rate matching
       let taxRateId: string | undefined;
       if (customer.address?.country && item.price_id) {
         try {
-          const price = await Price.findByPk(item.price_id);
+          const price = _priceMap.get(item.price_id);
           if (price?.product_id) {
-            const product = await Product.findByPk(price.product_id);
+            const { product } = price as any;
             if (product) {
-              const taxRate = await TaxRate.findMatchingRate({
-                country: customer.address.country,
-                state: customer.address.state,
-                postalCode: customer.address.postal_code,
-                taxCode: product.tax_code,
-                livemode,
-              });
-              taxRateId = taxRate?.id;
+              // Use pre-fetched tax rate if no product-specific tax_code,
+              // otherwise do a specific lookup
+              if (!product.tax_code) {
+                taxRateId = (_taxRateForCustomer as any)?.id;
+              } else {
+                const taxRate = await TaxRate.findMatchingRate({
+                  country: customer.address.country,
+                  state: customer.address.state,
+                  postalCode: customer.address.postal_code,
+                  taxCode: product.tax_code,
+                  livemode,
+                });
+                taxRateId = taxRate?.id;
+              }
             }
           }
         } catch (error) {
@@ -785,8 +813,10 @@ export async function cleanupInvoiceAndItems(invoiceId: string) {
     return;
   }
 
-  const removedItem = await InvoiceItem.destroy({ where: { invoice_id: invoiceId } });
-  const removedInvoice = await Invoice.destroy({ where: { id: invoiceId } });
+  const [removedItem, removedInvoice] = await Promise.all([
+    InvoiceItem.destroy({ where: { invoice_id: invoiceId } }),
+    Invoice.destroy({ where: { id: invoiceId } }),
+  ]);
   logger.info('cleanup invoice and items', { invoiceId, removedItem, removedInvoice });
 }
 
@@ -1345,21 +1375,26 @@ export const migrateSubscriptionPaymentMethodInvoice = async (
     }
   }
 
-  // 3. Get old and new payment method/currency
-  const oldPaymentCurrency = await PaymentCurrency.findByPk(oldCurrencyId);
+  // 3. Get old and new payment currency in parallel
+  const [oldPaymentCurrency, newPaymentCurrency] = await Promise.all([
+    PaymentCurrency.findByPk(oldCurrencyId),
+    PaymentCurrency.findByPk(newCurrencyId),
+  ]);
   if (!oldPaymentCurrency) {
     throw new Error(`Payment currency ${oldCurrencyId} not found`);
   }
-  const oldPaymentMethod = await PaymentMethod.findByPk(oldPaymentCurrency.payment_method_id);
-  if (!oldPaymentMethod) {
-    throw new Error(`Payment method for currency ${oldCurrencyId} not found`);
-  }
-
-  const newPaymentCurrency = await PaymentCurrency.findByPk(newCurrencyId);
   if (!newPaymentCurrency) {
     throw new Error(`Payment currency ${newCurrencyId} not found`);
   }
-  const newPaymentMethod = await PaymentMethod.findByPk(newPaymentCurrency.payment_method_id);
+
+  // Get old and new payment method in parallel
+  const [oldPaymentMethod, newPaymentMethod] = await Promise.all([
+    PaymentMethod.findByPk(oldPaymentCurrency.payment_method_id),
+    PaymentMethod.findByPk(newPaymentCurrency.payment_method_id),
+  ]);
+  if (!oldPaymentMethod) {
+    throw new Error(`Payment method for currency ${oldCurrencyId} not found`);
+  }
   if (!newPaymentMethod) {
     throw new Error(`Payment method for currency ${newCurrencyId} not found`);
   }

package/api/src/libs/notification/template/customer-auto-recharge-daily-limit-exceeded.ts

@@ -29,9 +29,7 @@ interface CustomerAutoRechargeDailyLimitExceededEmailTemplateContext {
   customerIndexUrl: string;
 }
 
-export class CustomerAutoRechargeDailyLimitExceededEmailTemplate
-  implements BaseEmailTemplate<CustomerAutoRechargeDailyLimitExceededEmailTemplateContext>
-{
+export class CustomerAutoRechargeDailyLimitExceededEmailTemplate implements BaseEmailTemplate<CustomerAutoRechargeDailyLimitExceededEmailTemplateContext> {
   options: CustomerAutoRechargeDailyLimitExceededEmailTemplateOptions;
 
   constructor(options: CustomerAutoRechargeDailyLimitExceededEmailTemplateOptions) {

package/api/src/libs/notification/template/customer-auto-recharge-failed.ts

@@ -46,9 +46,7 @@ interface CustomerAutoRechargeFailedEmailTemplateContext {
   isSkipped: boolean;
 }
 
-export class CustomerAutoRechargeFailedEmailTemplate
-  implements BaseEmailTemplate<CustomerAutoRechargeFailedEmailTemplateContext>
-{
+export class CustomerAutoRechargeFailedEmailTemplate implements BaseEmailTemplate<CustomerAutoRechargeFailedEmailTemplateContext> {
   options: CustomerAutoRechargeFailedEmailTemplateOptions;
 
   constructor(options: CustomerAutoRechargeFailedEmailTemplateOptions) {

package/api/src/libs/notification/template/customer-credit-grant-granted.ts

@@ -21,9 +21,7 @@ interface CustomerCreditGrantGrantedEmailTemplateContext {
   at: string;
 }
 
-export class CustomerCreditGrantGrantedEmailTemplate
-  implements BaseEmailTemplate<CustomerCreditGrantGrantedEmailTemplateContext>
-{
+export class CustomerCreditGrantGrantedEmailTemplate implements BaseEmailTemplate<CustomerCreditGrantGrantedEmailTemplateContext> {
   options: CustomerCreditGrantGrantedEmailTemplateOptions;
 
   constructor(options: CustomerCreditGrantGrantedEmailTemplateOptions) {

package/api/src/libs/notification/template/customer-credit-insufficient.ts

@@ -37,9 +37,7 @@ interface CustomerCreditInsufficientEmailTemplateContext {
   at: string;
 }
 
-export class CustomerCreditInsufficientEmailTemplate
-  implements BaseEmailTemplate<CustomerCreditInsufficientEmailTemplateContext>
-{
+export class CustomerCreditInsufficientEmailTemplate implements BaseEmailTemplate<CustomerCreditInsufficientEmailTemplateContext> {
   options: CustomerCreditInsufficientEmailTemplateOptions;
 
   constructor(options: CustomerCreditInsufficientEmailTemplateOptions) {

package/api/src/libs/notification/template/customer-credit-low-balance.ts

@@ -26,9 +26,7 @@ interface CustomerCreditLowBalanceEmailTemplateContext {
   isCritical: boolean; // true if percentage < 1%
   rechargeUrl: string | null;
 }
-export class CustomerCreditLowBalanceEmailTemplate
-  implements BaseEmailTemplate<CustomerCreditLowBalanceEmailTemplateContext>
-{
+export class CustomerCreditLowBalanceEmailTemplate implements BaseEmailTemplate<CustomerCreditLowBalanceEmailTemplateContext> {
   // Notification configuration: 10 minute grace period before sending
   static readonly delay = 10 * 60; // seconds
 

package/api/src/libs/notification/template/customer-revenue-succeeded.ts

@@ -43,9 +43,7 @@ interface CustomerRevenueSucceededEmailTemplateContext {
  * @class CustomerRevenueSucceededEmailTemplate
  * @implements {BaseEmailTemplate<CustomerRevenueSucceededEmailTemplateContext>}
  */
-export class CustomerRevenueSucceededEmailTemplate
-  implements BaseEmailTemplate<CustomerRevenueSucceededEmailTemplateContext>
-{
+export class CustomerRevenueSucceededEmailTemplate implements BaseEmailTemplate<CustomerRevenueSucceededEmailTemplateContext> {
   options: CustomerRevenueSucceededEmailTemplateOptions;
 
   constructor(options: CustomerRevenueSucceededEmailTemplateOptions) {

package/api/src/libs/notification/template/customer-reward-succeeded.ts

@@ -64,9 +64,7 @@ interface CustomerRewardSucceededEmailTemplateContext {
  * @class CustomerRewardSucceededEmailTemplate
  * @implements {BaseEmailTemplate<CustomerRewardSucceededEmailTemplateContext>}
  */
-export class CustomerRewardSucceededEmailTemplate
-  implements BaseEmailTemplate<CustomerRewardSucceededEmailTemplateContext>
-{
+export class CustomerRewardSucceededEmailTemplate implements BaseEmailTemplate<CustomerRewardSucceededEmailTemplateContext> {
   options: CustomerRewardSucceededEmailTemplateOptions;
 
   constructor(options: CustomerRewardSucceededEmailTemplateOptions) {

package/api/src/libs/notification/template/one-time-payment-refund-succeeded.ts

@@ -29,9 +29,7 @@ interface OneTimePaymentRefundSucceededEmailTemplateContext {
   invoiceNumber?: string;
 }
 
-export class OneTimePaymentRefundSucceededEmailTemplate
-  implements BaseEmailTemplate<OneTimePaymentRefundSucceededEmailTemplateContext>
-{
+export class OneTimePaymentRefundSucceededEmailTemplate implements BaseEmailTemplate<OneTimePaymentRefundSucceededEmailTemplateContext> {
   options: OneTimePaymentRefundSucceededEmailTemplateOptions;
 
   constructor(options: OneTimePaymentRefundSucceededEmailTemplateOptions) {

package/api/src/libs/notification/template/one-time-payment-succeeded.ts

@@ -37,9 +37,7 @@ interface OneTimePaymentSucceededEmailTemplateContext {
  * @class OneTimePaymentSucceededEmailTemplate
  * @implements {BaseEmailTemplate<OneTimePaymentSucceededEmailTemplateContext>}
  */
-export class OneTimePaymentSucceededEmailTemplate
-  implements BaseEmailTemplate<OneTimePaymentSucceededEmailTemplateContext>
-{
+export class OneTimePaymentSucceededEmailTemplate implements BaseEmailTemplate<OneTimePaymentSucceededEmailTemplateContext> {
   options: OneTimePaymentSucceededEmailTemplateOptions;
 
   constructor(options: OneTimePaymentSucceededEmailTemplateOptions) {

package/api/src/libs/notification/template/subscription-renew-failed.ts

@@ -50,9 +50,7 @@ interface SubscriptionRenewFailedEmailTemplateContext {
   payer: string;
 }
 
-export class SubscriptionRenewFailedEmailTemplate
-  implements BaseEmailTemplate<SubscriptionRenewFailedEmailTemplateContext>
-{
+export class SubscriptionRenewFailedEmailTemplate implements BaseEmailTemplate<SubscriptionRenewFailedEmailTemplateContext> {
   options: SubscriptionRenewFailedEmailTemplateOptions;
 
   constructor(options: SubscriptionRenewFailedEmailTemplateOptions) {

package/api/src/libs/notification/template/subscription-slippage-exceeded.ts

@@ -27,9 +27,7 @@ interface SubscriptionSlippageExceededEmailTemplateContext {
   customActions: any[];
 }
 
-export class SubscriptionSlippageExceededEmailTemplate
-  implements BaseEmailTemplate<SubscriptionSlippageExceededEmailTemplateContext>
-{
+export class SubscriptionSlippageExceededEmailTemplate implements BaseEmailTemplate<SubscriptionSlippageExceededEmailTemplateContext> {
   options: SubscriptionSlippageExceededEmailTemplateOptions;
 
   constructor(options: SubscriptionSlippageExceededEmailTemplateOptions) {

package/api/src/libs/notification/template/subscription-slippage-warning.ts

@@ -29,9 +29,7 @@ interface SubscriptionSlippageWarningEmailTemplateContext {
   customActions: any[];
 }
 
-export class SubscriptionSlippageWarningEmailTemplate
-  implements BaseEmailTemplate<SubscriptionSlippageWarningEmailTemplateContext>
-{
+export class SubscriptionSlippageWarningEmailTemplate implements BaseEmailTemplate<SubscriptionSlippageWarningEmailTemplateContext> {
   options: SubscriptionSlippageWarningEmailTemplateOptions;
 
   constructor(options: SubscriptionSlippageWarningEmailTemplateOptions) {

package/api/src/libs/notification/template/subscription-succeeded.ts

@@ -68,7 +68,7 @@ export class SubscriptionSucceededEmailTemplate extends BaseSubscriptionEmailTem
 
         return Boolean(
           ['disabled', 'minted', 'sent', 'error'].includes(checkoutSession?.nft_mint_status as string) &&
-            (invoice?.payment_intent_id || (invoice && +invoice.amount_remaining === 0))
+          (invoice?.payment_intent_id || (invoice && +invoice.amount_remaining === 0))
         );
       },
       { timeout: 1000 * 10, interval: 1000 }

package/api/src/libs/pagination.ts

@@ -140,17 +140,22 @@ function calculateFetchStrategy<T>(
       return { fetchLimit: Math.max(sourceCount, 1000), fetchOffset: 0 };
     }
 
-    // For database sources with multiple sources, use conservative strategy
+    // For database sources with multiple sources, use demand-driven strategy
     if (sourceMeta?.type === 'database') {
       if (sources.length > 1) {
-        // For multi-source scenarios, we need more data to ensure correct merging
-        // Especially for later pages, estimation can be inaccurate
-        const bufferMultiplier = Math.max(3, Math.ceil(page * 1.5)); // More aggressive buffer for later pages
-        const minDataRatio = page <= 2 ? 0.6 : 0.8; // Get more data for later pages
-        const fetchLimit = Math.min(
-          sourceCount,
-          Math.max(pageSize * bufferMultiplier, Math.ceil(sourceCount * minDataRatio))
-        );
+        // Multi-source merge fetches from offset=0 and merge-sorts in memory.
+        // We need (offset + pageSize) items after merging. Since we don't know
+        // how items interleave between sources, fetch (offset + pageSize) from
+        // each source with a buffer for merge uncertainty.
+        //
+        // Previous approach used sourceCount * 0.6~0.8 which over-fetched
+        // massively for early pages (e.g. page 1 fetched 2000+ rows) and still
+        // under-fetched for late pages. This demand-driven approach fetches
+        // proportionally to the page position — fast for early pages, more data
+        // only when needed for later pages.
+        const needed = offset + pageSize;
+        const buffer = Math.max(pageSize * 3, 50); // generous buffer for interleave uncertainty
+        const fetchLimit = Math.min(sourceCount, needed + buffer);
         return { fetchLimit, fetchOffset: 0 };
       }
       // Single database source can use precise offset

package/api/src/libs/payment.ts

@@ -387,20 +387,20 @@ export async function isDelegationSufficientForPayment(args: {
         delegator,
         source,
       });
-      return { sufficient: false, reason: 'NO_DELEGATION' };
+      return { sufficient: false, reason: 'NO_DELEGATION', state };
     }
 
     // have transfer permissions?
     const grant = (state as DelegateState).ops.find((x: any) => x.key === OCAP_PAYMENT_TX_TYPE)?.value;
     if (!grant) {
-      return { sufficient: false, reason: 'NO_TRANSFER_PERMISSION' };
+      return { sufficient: false, reason: 'NO_TRANSFER_PERMISSION', state };
     }
 
     // check token limits
     if (grant.limit && Array.isArray(grant.limit.tokens) && grant.limit.tokens.length > 0) {
       const tokenLimit = grant.limit.tokens.find((x: any) => x.address === tokenAddress);
       if (!tokenLimit) {
-        return { sufficient: false, reason: 'NO_TOKEN_PERMISSION' };
+        return { sufficient: false, reason: 'NO_TOKEN_PERMISSION', state };
       }
 
       // FIXME: @wangshijun check other conditions in the token limit: txCount, totalAllowance, validUntil, rateLimit
@@ -411,7 +411,7 @@ export async function isDelegationSufficientForPayment(args: {
         const allWalletAddresses = [wallet.address, ...migratedFrom];
         const hasValidTo = allWalletAddresses.some((addr) => tokenLimit.to.includes(addr));
         if (!hasValidTo) {
-          return { sufficient: false, reason: 'NO_TRANSFER_TO' };
+          return { sufficient: false, reason: 'NO_TRANSFER_TO', state };
         }
       }
 
@@ -426,12 +426,14 @@ export async function isDelegationSufficientForPayment(args: {
             return {
               sufficient: false,
               reason: 'NO_ENOUGH_ALLOWANCE',
+              state,
             };
           }
         } else if (totalAmount.gt(allowance)) {
           return {
             sufficient: false,
             reason: 'NO_ENOUGH_ALLOWANCE',
+            state,
           };
         }
       }
@@ -441,7 +443,7 @@ export async function isDelegationSufficientForPayment(args: {
     const { tokens } = await client.getAccountTokens({ address: delegator, token: tokenAddress });
     const [token] = tokens;
     if (!token) {
-      return { sufficient: false, reason: 'NO_TOKEN' };
+      return { sufficient: false, reason: 'NO_TOKEN', state };
     }
 
     if (new BN(token.balance).lt(totalAmount)) {
@@ -449,6 +451,7 @@ export async function isDelegationSufficientForPayment(args: {
         sufficient: false,
         reason: 'NO_ENOUGH_TOKEN',
         token,
+        state,
         requestedAmount: totalAmount.toString(),
       };
     }
@@ -602,7 +605,11 @@ export async function getTokenLimitsForDelegation(
   paymentMethod: PaymentMethod,
   paymentCurrency: PaymentCurrency,
   address: string,
-  amount: string
+  amount: string,
+  // Optional: if caller already fetched DelegateState (e.g. isDelegationSufficientForPayment),
+  // pass it here to skip a redundant chain RPC. Caller MUST use state from the same request
+  // to avoid stale-balance issues (see note on delegationCache above).
+  delegateState?: DelegateState | null
 ): Promise<TokenLimit[]> {
   const hasMetered = items.some((x) => x.price.recurring?.usage_type === 'metered');
   const allowance = hasMetered ? '0' : amount;
@@ -618,8 +625,16 @@ export async function getTokenLimitsForDelegation(
   };
 
   if (paymentMethod.type === 'arcblock') {
-    const client = paymentMethod.getOcapClient();
-    const { state } = await client.getDelegateState({ address });
+    let state: DelegateState | null | undefined = delegateState;
+    if (state === undefined) {
+      const client = paymentMethod.getOcapClient();
+      // CF Workers: warm up chain context to avoid setTimeout(resolve,0) hang on cold client.
+      await client.getContext();
+      ({ state } = await client.getDelegateState({ address }));
+      logger.info('getTokenLimitsForDelegation: fetched DelegateState from chain', { address });
+    } else {
+      logger.info('getTokenLimitsForDelegation: reused DelegateState from caller', { address });
+    }
 
     // If we never delegated before
     if (!state) {
@@ -630,10 +645,10 @@ export async function getTokenLimitsForDelegation(
       return [entry];
     }
 
-    const op = state.ops.find((x) => x.key === OCAP_PAYMENT_TX_TYPE);
+    const op = state.ops.find((x: any) => x.key === OCAP_PAYMENT_TX_TYPE);
     if (op && Array.isArray(op.value.limit?.tokens) && op.value.limit.tokens.length > 0) {
       const tokenLimits = cloneDeep(op.value.limit.tokens);
-      const index = op.value.limit.tokens.findIndex((x) => x.address === paymentCurrency.contract);
+      const index = op.value.limit.tokens.findIndex((x: any) => x.address === paymentCurrency.contract);
       // we are updating an existing token limit
       if (index > -1) {
         const limit = op.value.limit.tokens[index] as TokenLimit;

package/api/src/libs/security.ts

@@ -1,5 +1,6 @@
 import { auth } from '@blocklet/sdk/lib/middlewares';
 import { getVerifyData, verify } from '@blocklet/sdk/lib/util/verify-sign';
+import { verifyLoginToken } from '@blocklet/sdk/lib/util/verify-session';
 import { getWallet } from '@blocklet/sdk/lib/wallet';
 import type { NextFunction, Request, Response } from 'express';
 import type { Model } from 'sequelize';
@@ -39,6 +40,56 @@ export function authenticate<T extends Model>({
   ensureLogin,
 }: PermissionSpec<T>) {
   return async (req: Request, res: Response, next: NextFunction) => {
+    // Dev-only bypass: requires both NODE_ENV=development AND the explicit
+    // opt-in env ENABLE_DEV_FAKE_AUTH=1, plus the x-dev-fake-did header on
+    // the request. Lets mobile demo clients that don't go through DID Connect
+    // (e.g. the local-tunnel backend which bypasses Blocklet Server) still
+    // exercise real handlers. Production never sets ENABLE_DEV_FAKE_AUTH, so
+    // this branch can't trigger there; dev defaults off, so we don't
+    // accidentally regress to fake auth after wiring the real flow.
+    if (process.env.NODE_ENV === 'development' && process.env.ENABLE_DEV_FAKE_AUTH === '1') {
+      const devDid = req.get('x-dev-fake-did');
+      if (devDid) {
+        req.user = {
+          did: devDid,
+          role: 'owner', // satisfies routes that require owner/admin
+          provider: 'dev',
+          fullName: 'dev-fake-user',
+          walletOS: '',
+          via: 'dev',
+        };
+        return next();
+      }
+    }
+
+    // Authenticate by Authorization: Bearer <login-token>. The token is a JWT
+    // signed with this blocklet's session secret (see @blocklet/sdk session
+    // middleware). When clients hit us through a tunnel that bypasses Blocklet
+    // Server (so x-user-did is NOT injected), we need to verify the token
+    // ourselves. verifyLoginToken does local JWT signature verification, no
+    // HTTP callback. On success we forward into the existing x-user-did branch
+    // by populating req.headers so the role/mine/record cascade below applies
+    // unchanged.
+    const authHeader = req.get('authorization');
+    if (authHeader && /^Bearer\s+/i.test(authHeader) && !req.headers['x-user-did']) {
+      const token = authHeader.replace(/^Bearer\s+/i, '').trim();
+      if (token) {
+        const session = await verifyLoginToken({ token, strictMode: false }).catch(() => null);
+        if (session?.did) {
+          // Some BS versions put a bare base58 address in the JWT, others
+          // the canonical `did:abt:…` form. Normalize so downstream code
+          // (entitlement self-check, mine: lookups by req.user.did) sees the
+          // same shape clients send in `customer_did` query params.
+          const canonicalDid = session.did.startsWith('did:abt:') ? session.did : `did:abt:${session.did}`;
+          req.headers['x-user-did'] = canonicalDid;
+          req.headers['x-user-role'] = `blocklet-${session.role || 'user'}`;
+          req.headers['x-user-provider'] = session.provider || 'wallet';
+          req.headers['x-user-fullname'] = encodeURIComponent(session.fullName || '');
+          req.headers['x-user-wallet-os'] = session.walletOS || '';
+        }
+      }
+    }
+
     // authenticate by component call
     const sig = req.get('x-component-sig');
     if (component && sig) {

package/api/src/libs/session.ts

@@ -5,7 +5,7 @@ import { BN, fromTokenToUnit, fromUnitToToken } from '@ocap/util';
 import cloneDeep from 'lodash/cloneDeep';
 import isEqual from 'lodash/isEqual';
 import pAll from 'p-all';
-import { omit } from 'lodash';
+import omit from 'lodash/omit';
 import dayjs from './dayjs';
 import { validCoupon } from './discount/coupon';
 import { getPriceUintAmountByCurrency, getPriceCurrencyOptions } from './price';

package/api/src/libs/subscription.ts

@@ -1357,8 +1357,20 @@ export async function isSubscriptionOverdraftProtectionEnabled(subscription: Sub
       throw new Error(`PaymentMethod not found in ${subscription.id}`);
     }
 
+    // Overdraft protection is only meaningful for on-chain (arcblock) payment
+    // methods where users stake tokens. IAP / Stripe channels have no notion of
+    // staking; return disabled-default silently rather than throwing into the
+    // outer catch (which would spam the error log on every google_play /
+    // app_store / stripe subscription event).
     if (paymentMethod.type !== 'arcblock') {
-      throw new Error(`PaymentMethod type not supported in ${subscription.id}`);
+      return {
+        enabled: false,
+        remaining: '0',
+        used: '0',
+        shouldPay: '0',
+        unused: '0',
+        revokedStake: '0',
+      };
     }
     if (!subscription.overdraft_protection) {
       return {