payment-kit 1.27.2 → 1.29.0

package/api/src/libs/audit.ts

@@ -8,14 +8,63 @@ import { context } from './context';
 
 const API_VERSION = '2023-09-05';
 
-export async function createEvent(scope: string, type: LiteralUnion<EventType, string>, model: any, options: any = {}) {
+/**
+ * Invoke every registered listener for `eventName` and await any Promise
+ * results. EventEmitter.emit() returns sync — listener async work would
+ * otherwise run as detached microtasks and die when the CF Workers handler
+ * unwinds. We want listeners (notably queues/event.ts's event.created
+ * handler that drives webhook delivery) to complete inside createEvent's
+ * Promise so waitUntil covers the whole chain.
+ */
+async function emitAndAwait(eventName: string, ...args: any[]): Promise<void> {
+  const listeners = events.rawListeners(eventName);
+  for (const listener of listeners) {
+    try {
+      const result = (listener as any)(...args);
+      if (result && typeof result.then === 'function') {
+        // eslint-disable-next-line no-await-in-loop -- sequential await keeps listener ordering deterministic for waitUntil chains
+        await result;
+      }
+    } catch (err: any) {
+      console.error('[audit emitAndAwait]', eventName, err?.message || err);
+    }
+  }
+}
+
+export function createEvent(
+  scope: string,
+  type: LiteralUnion<EventType, string>,
+  model: any,
+  options: any = {}
+): Promise<void> {
+  // Context-aware tracking for CF Workers:
+  // - HTTP requests: use ctx.waitUntil (non-blocking, like Blocklet's fire-and-forget)
+  // - Queue consumer/Cron: use __cfPendingJobs__ (blocking, listeners must complete)
+  // - Blocklet Server: no tracking needed (long-lived process)
+  const promise = doCreateEvent(scope, type, model, options);
+  const isHttp = (globalThis as any).__cfHttpContext__;
+  if (isHttp) {
+    const waitUntil = (globalThis as any).__cfWaitUntil__;
+    if (typeof waitUntil === 'function') {
+      waitUntil(promise.catch((err: any) => console.error('[createEvent]', type, err?.message || err)));
+    }
+  } else {
+    const pending = (globalThis as any).__cfPendingJobs__;
+    if (Array.isArray(pending)) {
+      pending.push(promise.catch((err: any) => console.error('[createEvent]', type, err?.message || err)));
+    }
+  }
+  return promise;
+}
+
+async function doCreateEvent(scope: string, type: LiteralUnion<EventType, string>, model: any, options: any = {}) {
   const data: any = {
     object: model.dataValues,
   };
   if (type.endsWith('updated')) {
     data.previous_attributes = pick(model._previousDataValues, options.fields);
   }
-  // console.log('createEvent', scope, type, data, options);
+
   const event = await Event.create({
     type,
     api_version: API_VERSION,
@@ -24,17 +73,23 @@ export async function createEvent(scope: string, type: LiteralUnion<EventType, s
     object_type: scope,
     data,
     request: {
-      // FIXME:
       id: '',
       idempotency_key: '',
       requested_by: options.requestedBy || context.getRequestedBy() || 'system',
     },
     metadata: {},
-    pending_webhooks: 99, // force all events goto the event queue
+    pending_webhooks: 99,
   });
 
-  events.emit('event.created', { id: event.id });
-  events.emit(event.type, data.object, options);
+  // Synchronously await listener chains so the HTTP handler's waitUntil
+  // scope covers the full handleEvent → addWebhookJob → push pipeline.
+  // EventEmitter.emit() returns sync and discards listener Promises — on
+  // CF Workers that leaves the listener microtask racing against worker
+  // termination, and `customer.subscription.started` / `.deleted` events
+  // fired at the tail of HTTP handlers were observed to lose their first
+  // delivery attempt because of it.
+  await emitAndAwait('event.created', { id: event.id });
+  await emitAndAwait(event.type, data.object, options);
 }
 
 export async function createStatusEvent(
@@ -57,7 +112,6 @@ export async function createStatusEvent(
     return;
   }
 
-  // console.log('createStatusEvent', scope, prefix, config, data, options);
   const suffix = config[data.object.status];
   const event = await Event.create({
     type: [prefix, suffix].join('.'),
@@ -67,17 +121,16 @@ export async function createStatusEvent(
     object_type: scope,
     data,
     request: {
-      // FIXME:
       id: '',
       idempotency_key: '',
       requested_by: options.requestedBy || context.getRequestedBy() || 'system',
     },
     metadata: {},
-    pending_webhooks: 99, // force all events goto the event queue
+    pending_webhooks: 99,
   });
 
-  events.emit('event.created', { id: event.id });
-  events.emit(event.type, data.object);
+  await emitAndAwait('event.created', { id: event.id });
+  await emitAndAwait(event.type, data.object);
 }
 
 export async function createCustomEvent(
@@ -97,7 +150,6 @@ export async function createCustomEvent(
     return;
   }
 
-  // console.log('createCustomEvent', scope, prefix, type, data, options);
   const event = await Event.create({
     type: [prefix, suffix].join('.'),
     api_version: API_VERSION,
@@ -106,26 +158,20 @@ export async function createCustomEvent(
     object_type: scope,
     data,
     request: {
-      // FIXME:
       id: '',
       idempotency_key: '',
       requested_by: options.requestedBy || context.getRequestedBy() || 'system',
     },
     metadata: {},
-    pending_webhooks: 99, // force all events goto the event queue
+    pending_webhooks: 99,
   });
 
-  events.emit('event.created', { id: event.id });
-  events.emit(event.type, data.object);
+  await emitAndAwait('event.created', { id: event.id });
+  await emitAndAwait(event.type, data.object);
 }
 
 /**
  * 创建自定义事件，无需依赖模型对象
- * @param type 完整的事件类型，格式为 prefix.suffix
- * @param objectType 对象类型
- * @param objectId 对象ID
- * @param data 事件数据
- * @param options 额外选项
  */
 export async function createFlexibleEvent(
   type: string,
@@ -153,10 +199,10 @@ export async function createFlexibleEvent(
       requested_by: requestedBy || context.getRequestedBy() || 'system',
     },
     metadata,
-    pending_webhooks: 99, // force all events goto the event queue
+    pending_webhooks: 99,
   });
 
-  events.emit('event.created', { id: event.id });
-  events.emit(type, data);
+  await emitAndAwait('event.created', { id: event.id });
+  await emitAndAwait(type, data);
   return event;
 }

package/api/src/libs/auth.ts

@@ -3,7 +3,7 @@ import path from 'path';
 import AuthStorage from '@arcblock/did-connect-storage-nedb';
 // @ts-ignore
 import { BlockletService } from '@blocklet/sdk/service/auth';
-import { getWallet } from '@blocklet/sdk/lib/wallet';
+import { getWallet, getAccessWallet } from '@blocklet/sdk/lib/wallet';
 import { WalletAuthenticator } from '@blocklet/sdk/lib/wallet-authenticator';
 import { WalletHandlers } from '@blocklet/sdk/lib/wallet-handler';
 import type { Request } from 'express';
@@ -13,9 +13,56 @@ import type { WalletObject } from '@ocap/wallet';
 import env from './env';
 import logger from './logger';
 
+// Workaround #2: @blocklet/sdk's notification.getSender() uses
+// `getWallet().address` (BLOCKLET_APP_SK derived) as the sender appDid for
+// relay/EventBus broadcasts. On migrated blocklets that address (e.g. zNKti3…)
+// is a rotating session id that the relay does not recognise, surfacing as:
+//   "Sender blocklet does not exist: <addr>"
+//   "Failed to broadcast event via relay: payment_intent.succeeded"
+// The relay/EventBus calls in notification.js invoke `(0, exports.getSender)()`
+// at send time, so mutating the module's own `exports.getSender` intercepts
+// every call site. We must use `require()` (not `import default`) — the module
+// sets `exports.default` to a subset object that does NOT include getSender,
+// so the default-import alias cannot reach the live `exports.getSender`.
+//
+// Path must be `@blocklet/sdk/service/notification` (no `lib/`) — in Node it
+// is a thin re-export that resolves via the module cache to the same object
+// as `@blocklet/sdk/lib/service/notification`; in CF Workers the esbuild
+// config aliases it to a no-op shim (patching a no-op is harmless). Using
+// the `lib/` path breaks the CF build because it does not have an alias
+// and falls through to `@blocklet/sdk` → `shims/blocklet-sdk/index.ts/lib/...`.
+// Same root cause as the WalletAuthenticator override below — remove once the
+// upstream sdk is patched.
+// eslint-disable-next-line @typescript-eslint/no-var-requires, global-require, import/no-extraneous-dependencies
+const notificationExports = require('@blocklet/sdk/service/notification');
+
+notificationExports.getSender = () => ({
+  appDid: process.env.BLOCKLET_APP_ID || getWallet(undefined, '', 'sk').address,
+  wallet: getAccessWallet(),
+});
+logger.info('[sdk-patch] notification.getSender overridden', {
+  appDid: notificationExports.getSender().appDid,
+  expectedAppId: process.env.BLOCKLET_APP_ID,
+});
+
 export const wallet: WalletObject = getWallet();
 export const ethWallet: WalletObject = getWallet('ethereum');
-export const authenticator = new WalletAuthenticator();
+
+// Workaround for migrated blocklets where `BLOCKLET_APP_SK` is a rotating session
+// key whose derived address ≠ appId. Upstream @blocklet/sdk's WalletAuthenticator
+// passes `wallet: getWallet()` to did-connect-js, so outer.agentDid becomes that
+// rotating address. Meanwhile the federated cert (signed by master) sets
+// agentDid = `did:abt:${verifySite.appId}` (permanent), so the wallet-side strict
+// check `cert.agentDid === outer.agentDid` fails with "Agent did does not match
+// with certificate issuer."
+//
+// Force the authenticator to derive its signing wallet from BLOCKLET_APP_PK
+// (permanent app pk → address = appId), aligning with the fix in
+// @blocklet/sdk PR #12810 that already corrected getDelegatee. Remove once the
+// upstream wallet-authenticator.ts is patched accordingly.
+export const authenticator = new WalletAuthenticator({
+  wallet: getWallet(undefined, '', 'sk'),
+});
 export const handlers = new WalletHandlers({
   authenticator,
   tokenStorage: new AuthStorage({

package/api/src/libs/chain-error.ts

@@ -0,0 +1,31 @@
+import CustomError from './error';
+
+export function parseChainError(err: unknown): CustomError {
+  const msg = (err as Error)?.message ?? String(err);
+
+  const gasMatch = msg.match(
+    /Insufficient fund to pay for tx cost from (\w+)[\s\S]*?expected\s+([\d.]+)\s+(\w+)[\s\S]*?got\s+([\d.]+)/
+  );
+  if (gasMatch) {
+    return new CustomError('INSUFFICIENT_GAS', 'Main account lacks gas token for tx cost').withDetails({
+      account: gasMatch[1],
+      required: gasMatch[2],
+      available: gasMatch[4],
+      token: gasMatch[3],
+    });
+  }
+
+  // Chain rejects gas-payer JWT when the signing account has no on-chain state
+  // (fresh DID that never broadcast a DeclareTx). The wallet shouldn't attach
+  // x-gas-payer-* headers in that case, but surface a clean code/message so the
+  // UI doesn't render the raw GraphQL string. See #1356.
+  const gasPayerNotOnChain = msg.match(/Gas payer (\w+)[\s\S]*?does not exist on chain/i);
+  if (gasPayerNotOnChain) {
+    return new CustomError(
+      'GAS_PAYER_NOT_ON_CHAIN',
+      'Wallet account has no on-chain history yet; please fund or transact once before paying'
+    ).withDetails({ account: gasPayerNotOnChain[1] });
+  }
+
+  return new CustomError('TX_REJECTED', msg).withDetails({ raw: msg });
+}

package/api/src/libs/entitlement.ts

@@ -0,0 +1,399 @@
+// Cross-channel entitlement check.
+//
+// Goal: given a customer DID and a product_id, return whether the customer
+// currently has the entitlement, regardless of which channel funded it
+// (Stripe / on-chain / Google Play / App Store / one-time credit purchase).
+//
+// MVP scope (A3-MVP):
+//   - Subscription-funded entitlements are fully supported across all channels
+//   - One-time-purchase credit grants are supported when CreditGrant.metadata
+//     carries a `product_id` field (existing flows already do this for
+//     credit-grant-type Products)
+//   - When multiple subscriptions cover the same product (rare — e.g. user
+//     buys on iOS and on web), we pick by status priority (active > trialing
+//     > paused > past_due) and tie-break by latest current_period_end
+//
+// Channel inference:
+//   - Subscription.channel (A0 column) wins when set
+//   - Falls back to PaymentMethod.type — for legacy subscriptions written
+//     before A0, this maps stripe/arcblock/ethereum/base correctly
+
+import { Op } from 'sequelize';
+
+import { CreditGrant, Customer, PaymentMethod, Price, Product, Subscription, SubscriptionItem } from '../store/models';
+
+// Subscriptions in `active`/`trialing` should still grant entitlement only
+// while the current period hasn't elapsed. Without this, a row whose
+// EXPIRED webhook never landed (network drop, RTDN race onto a duplicate
+// row, etc.) stays status=active forever and the customer keeps Pro long
+// after the platform has stopped billing them. `past_due`/`paused` are
+// allowed to outrun current_period_end — those statuses are themselves
+// the "should-have-renewed-but-hasn't" markers and the grace window is
+// platform-controlled, not period-bounded.
+const stillInActivePeriod = () => ({
+  [Op.or]: [
+    { status: ['past_due', 'paused'] as any },
+    {
+      status: ['active', 'trialing'] as any,
+      current_period_end: { [Op.gt]: Math.floor(Date.now() / 1000) },
+    },
+  ],
+});
+
+export type Channel = 'stripe' | 'app_store' | 'google_play' | 'arcblock' | 'ethereum' | 'base' | 'bitcoin' | null;
+
+export type EntitlementCheckResult = {
+  active: boolean;
+  channel: Channel;
+  expires_at: number | null;
+  subscription_id: string | null;
+  source: 'subscription' | 'one_time' | null;
+  credit_remaining?: string;
+};
+
+const SUBSCRIPTION_STATUS_PRIORITY: Record<string, number> = {
+  active: 0,
+  trialing: 1,
+  paused: 2,
+  past_due: 3,
+};
+const ACTIVE_STATUSES = new Set(['active', 'trialing']);
+
+function inactiveResult(): EntitlementCheckResult {
+  return { active: false, channel: null, expires_at: null, subscription_id: null, source: null };
+}
+
+async function inferChannelFromSubscription(sub: Subscription): Promise<Channel> {
+  const ch = (sub as any).channel as Channel | undefined;
+  if (ch) return ch;
+  if (!sub.default_payment_method_id) return null;
+  const method = await PaymentMethod.findByPk(sub.default_payment_method_id);
+  return (method?.type as Channel) ?? null;
+}
+
+async function inferChannelFromGrant(grant: CreditGrant): Promise<Channel> {
+  // Most CreditGrant rows store the originating payment_method_id in metadata.
+  const pmId = grant.metadata?.payment_method_id || grant.metadata?.paymentMethodId;
+  if (!pmId) return null;
+  const method = await PaymentMethod.findByPk(pmId);
+  return (method?.type as Channel) ?? null;
+}
+
+function pickBestSubscription(subs: Subscription[]): Subscription | undefined {
+  return [...subs].sort((a, b) => {
+    const pa = SUBSCRIPTION_STATUS_PRIORITY[a.status as string] ?? 99;
+    const pb = SUBSCRIPTION_STATUS_PRIORITY[b.status as string] ?? 99;
+    if (pa !== pb) return pa - pb;
+    // tie-break: later expiry wins
+    return (b.current_period_end ?? 0) - (a.current_period_end ?? 0);
+  })[0];
+}
+
+/**
+ * The channel SKU stored on an IAP subscription (Apple/Google product id).
+ * Its presence marks a subscription whose product MUST be resolved live via the
+ * Product↔SKU mapping rather than via its (possibly stale) SubscriptionItem.
+ */
+function channelSkuOf(sub: any): string | undefined {
+  const pd = sub?.payment_details as
+    | { app_store?: { product_id?: string }; google_play?: { product_id?: string } }
+    | undefined;
+  return pd?.app_store?.product_id ?? pd?.google_play?.product_id;
+}
+
+/**
+ * Resolve customer DID → Customer row; returns null if not found.
+ * Exposed so listEntitlements can reuse the same lookup.
+ */
+function resolveCustomer(customer_did: string, livemode: boolean): Promise<Customer | null> {
+  return Customer.findOne({ where: { did: customer_did, livemode } });
+}
+
+/**
+ * Find all active subscriptions that grant `product_id` to this customer.
+ * Walks each subscription's items → price → product to do the match.
+ */
+async function findSubscriptionsCoveringProduct(
+  customer: Customer,
+  productId: string,
+  livemode: boolean
+): Promise<Subscription[]> {
+  const subs = await Subscription.findAll({
+    where: {
+      customer_id: customer.id,
+      livemode,
+      ...stillInActivePeriod(),
+    } as any,
+    include: [
+      {
+        model: SubscriptionItem,
+        as: 'items',
+        include: [{ model: Price, as: 'price', include: [{ model: Product, as: 'product' }] }],
+      },
+    ],
+  });
+  // Resolve the queried Product's channel SKUs from its Prices (Stripe-style:
+  // SKU binding lives on Price.metadata, not Product.metadata). One Product
+  // can have N Prices (monthly / yearly / promo), each bound to its own
+  // App Store SKU + Google Play SKU. Matching live against Prices means
+  // entitlement always reflects the bindings as configured NOW — does not
+  // depend on a product_id snapshot frozen into the subscription. A SKU
+  // rebind grants only the new product, not both (PR #1381 review P2).
+  //
+  // Multi-tenant scoping: the key includes the tenant (bundle_id /
+  // package_name) so a sub from App A doesn't accidentally satisfy a
+  // Price configured for App B that happens to share the SKU string —
+  // App Store / Play Console SKU namespaces are per-app, so two apps
+  // owning the literal string "pro_monthly" is the expected case.
+  const prices = await Price.findAll({ where: { product_id: productId, livemode } as any });
+  const appKeys = new Set<string>(); // ${bundle_id}:${sku}
+  const gpKeys = new Set<string>(); // ${package_name}:${sku}
+  for (const p of prices) {
+    const m = ((p as any).metadata as any) || {};
+    if (m.app_store_product_id && m.bundle_id) appKeys.add(`${m.bundle_id}:${m.app_store_product_id}`);
+    if (m.google_play_product_id && m.package_name) {
+      gpKeys.add(`${m.package_name}:${m.google_play_product_id}`);
+    }
+  }
+
+  return subs.filter((sub) => {
+    const pd = (sub as any).payment_details as
+      | {
+          app_store?: { product_id?: string; bundle_id?: string };
+          google_play?: { product_id?: string; package_name?: string };
+        }
+      | undefined;
+
+    // IAP subs that carry a channel SKU: resolve ONLY via the live channel-SKU ↔
+    // current Price metadata mapping. Deliberately ignore the (possibly stale)
+    // SubscriptionItem snapshot AND the legacy metadata.product_id — otherwise a
+    // SKU rebind would grant both the old item's product and the new mapping
+    // (PR #1381 review P2). This is the single authoritative rule for IAP, and
+    // listEntitlements applies the same mapping for consistency.
+    if (channelSkuOf(sub)) {
+      const appSku = pd?.app_store?.product_id;
+      const appBundle = pd?.app_store?.bundle_id;
+      const gpSku = pd?.google_play?.product_id;
+      const gpPkg = pd?.google_play?.package_name;
+      if (appSku && appBundle && appKeys.has(`${appBundle}:${appSku}`)) return true;
+      if (gpSku && gpPkg && gpKeys.has(`${gpPkg}:${gpSku}`)) return true;
+      return false;
+    }
+
+    // Stripe / legacy (no channel SKU stored): walk items → price → product,
+    // then the metadata snapshot.
+    const items = (sub as any).items as Array<{ price?: { product_id?: string } }> | undefined;
+    if (items?.some((it) => it.price?.product_id === productId)) return true;
+    return (sub.metadata as any)?.product_id === productId;
+  });
+}
+
+/**
+ * Find a CreditGrant tied to this customer + product, if any.
+ * Convention: CreditGrant.metadata.product_id matches.
+ */
+async function findGrantCoveringProduct(customer: Customer, productId: string): Promise<CreditGrant | null> {
+  const grants = await CreditGrant.findAll({
+    where: { customer_id: customer.id, status: 'granted' as any },
+  });
+  return grants.find((g) => g.metadata?.product_id === productId) ?? null;
+}
+
+function isGrantActive(grant: CreditGrant): boolean {
+  if (grant.expires_at && grant.expires_at * 1000 < Date.now()) return false;
+  // remaining_amount is stored as string (BN-friendly). Treat anything ≠ "0" as positive.
+  const remaining = grant.remaining_amount ?? '0';
+  return remaining !== '0' && remaining !== '0.0';
+}
+
+/**
+ * Check whether the customer currently holds the entitlement for `product_id`.
+ */
+export async function checkEntitlement({
+  customer_did,
+  product_id,
+  livemode = true,
+}: {
+  customer_did: string;
+  product_id: string;
+  livemode?: boolean;
+}): Promise<EntitlementCheckResult> {
+  const customer = await resolveCustomer(customer_did, livemode);
+  if (!customer) return inactiveResult();
+
+  // 1. Subscription path
+  const matching = await findSubscriptionsCoveringProduct(customer, product_id, livemode);
+  const best = pickBestSubscription(matching);
+  if (best) {
+    return {
+      active: ACTIVE_STATUSES.has(best.status as string),
+      channel: await inferChannelFromSubscription(best),
+      expires_at: best.current_period_end ?? null,
+      subscription_id: best.id,
+      source: 'subscription',
+    };
+  }
+
+  // 2. One-time credit-grant path
+  const grant = await findGrantCoveringProduct(customer, product_id);
+  if (grant) {
+    return {
+      active: isGrantActive(grant),
+      channel: await inferChannelFromGrant(grant),
+      expires_at: grant.expires_at ?? null,
+      subscription_id: null,
+      source: 'one_time',
+      credit_remaining: grant.remaining_amount,
+    };
+  }
+
+  return inactiveResult();
+}
+
+export type EntitlementListItem = {
+  product_id: string;
+  active: boolean;
+  channel: Channel;
+  expires_at: number | null;
+  subscription_id: string | null;
+  source: 'subscription' | 'one_time';
+  credit_remaining?: string;
+};
+
+/**
+ * List every entitlement this customer holds (one row per distinct product).
+ * Subscription items contribute first; CreditGrants add anything not already
+ * covered by a subscription.
+ */
+export async function listEntitlements({
+  customer_did,
+  livemode = true,
+}: {
+  customer_did: string;
+  livemode?: boolean;
+}): Promise<EntitlementListItem[]> {
+  const customer = await resolveCustomer(customer_did, livemode);
+  if (!customer) return [];
+
+  const subs = await Subscription.findAll({
+    where: {
+      customer_id: customer.id,
+      livemode,
+      ...stillInActivePeriod(),
+    } as any,
+    include: [
+      {
+        model: SubscriptionItem,
+        as: 'items',
+        include: [{ model: Price, as: 'price', include: [{ model: Product, as: 'product' }] }],
+      },
+    ],
+  });
+
+  // Group by product_id, picking best subscription per product. IAP subs that
+  // carry a channel SKU resolve via the live SKU→Product mapping (NOT their
+  // possibly-stale SubscriptionItem) so list agrees with checkEntitlement
+  // (PR #1381 review P2); everything else groups by items.
+  const productToSubs = new Map<string, Subscription[]>();
+  const addToGroup = (pid: string, sub: Subscription) => {
+    if (!productToSubs.has(pid)) productToSubs.set(pid, []);
+    productToSubs.get(pid)!.push(sub);
+  };
+
+  const skuSubs = subs.filter((s) => channelSkuOf(s));
+  if (skuSubs.length) {
+    // Build (tenant, SKU)→productId from the Price catalogue. Stripe-style
+    // schema: Price.metadata.{app_store,google_play}_product_id binds the
+    // channel SKU to a specific Price; that Price's product_id is the
+    // entitlement key. One Product with N Prices (monthly / yearly / promo)
+    // all roll up to the same entitlement — exactly the behaviour
+    // `entitlements.check(productId)` expects on the client side.
+    //
+    // Multi-tenant scoping: same SKU string can live in independent App
+    // Store / Play Console namespaces (two iOS or two Android apps wired
+    // into one Payment Kit), so the key includes the tenant
+    // (bundle_id / package_name). Without this, Map.set would silently
+    // overwrite collisions and route all subs to whichever Price was
+    // iterated last. Each sub reads its own tenant from payment_details
+    // (persisted at create time, backfilled for legacy rows).
+    const prices = await Price.findAll({ where: { livemode } as any });
+    const appKeyToPid = new Map<string, string>();
+    const gpKeyToPid = new Map<string, string>();
+    for (const p of prices) {
+      const m = ((p as any).metadata as any) || {};
+      if (m.app_store_product_id && m.bundle_id) {
+        appKeyToPid.set(`${m.bundle_id}:${m.app_store_product_id}`, p.product_id);
+      }
+      if (m.google_play_product_id && m.package_name) {
+        gpKeyToPid.set(`${m.package_name}:${m.google_play_product_id}`, p.product_id);
+      }
+    }
+    for (const sub of skuSubs) {
+      const pd = (sub as any).payment_details as
+        | {
+            app_store?: { product_id?: string; bundle_id?: string };
+            google_play?: { product_id?: string; package_name?: string };
+          }
+        | undefined;
+      const appSku = pd?.app_store?.product_id;
+      const appBundle = pd?.app_store?.bundle_id;
+      const gpSku = pd?.google_play?.product_id;
+      const gpPkg = pd?.google_play?.package_name;
+      const pid =
+        (appSku && appBundle && appKeyToPid.get(`${appBundle}:${appSku}`)) ||
+        (gpSku && gpPkg && gpKeyToPid.get(`${gpPkg}:${gpSku}`));
+      if (pid) addToGroup(pid, sub);
+    }
+  }
+
+  for (const sub of subs) {
+    // eslint-disable-next-line no-continue -- IAP-with-SKU handled above via live mapping
+    if (channelSkuOf(sub)) continue;
+    const items = (sub as any).items as Array<{ price?: { product_id?: string } }> | undefined;
+    const productIds = new Set(items?.map((it) => it.price?.product_id).filter(Boolean) as string[]);
+    for (const pid of productIds) addToGroup(pid, sub);
+  }
+
+  const subscriptionProductIds = new Set<string>();
+  // Run channel inference in parallel — each is a Sequelize lookup, no shared state.
+  const subscriptionRows = await Promise.all(
+    Array.from(productToSubs.entries()).map(async ([productId, candidates]) => {
+      const best = pickBestSubscription(candidates)!;
+      subscriptionProductIds.add(productId);
+      const item: EntitlementListItem = {
+        product_id: productId,
+        active: ACTIVE_STATUSES.has(best.status as string),
+        channel: await inferChannelFromSubscription(best),
+        expires_at: best.current_period_end ?? null,
+        subscription_id: best.id,
+        source: 'subscription',
+      };
+      return item;
+    })
+  );
+
+  // Add CreditGrant-funded entitlements for products not already covered
+  const grants = await CreditGrant.findAll({
+    where: { customer_id: customer.id, status: 'granted' as any },
+  });
+  const uncoveredGrants = grants.filter((g) => {
+    const pid = g.metadata?.product_id;
+    return pid && !subscriptionProductIds.has(pid);
+  });
+  const grantRows = await Promise.all(
+    uncoveredGrants.map(async (grant) => {
+      const item: EntitlementListItem = {
+        product_id: grant.metadata!.product_id,
+        active: isGrantActive(grant),
+        channel: await inferChannelFromGrant(grant),
+        expires_at: grant.expires_at ?? null,
+        subscription_id: null,
+        source: 'one_time',
+        credit_remaining: grant.remaining_amount,
+      };
+      return item;
+    })
+  );
+
+  return [...subscriptionRows, ...grantRows];
+}

package/api/src/libs/env.ts

@@ -18,6 +18,8 @@ export const depositVaultCronTime: string = process.env.DEPOSIT_VAULT_CRON_TIME
 export const creditConsumptionCronTime: string = process.env.CREDIT_CONSUMPTION_CRON_TIME || '0 */10 * * * *'; // 默认每 10 min 执行一次
 export const vendorStatusCheckCronTime: string = process.env.VENDOR_STATUS_CHECK_CRON_TIME || '0 */10 * * * *'; // 默认每 10 min 执行一次
 export const vendorReturnScanCronTime: string = process.env.VENDOR_RETURN_SCAN_CRON_TIME || '0 */10 * * * *'; // 默认每 10 min 执行一次
+export const iapReconcileCronTime: string = process.env.IAP_RECONCILE_CRON_TIME || '0 */5 * * * *'; // 默认每 5 min 执行一次:webhook 兜底,拉 App Store / Google Play 订阅最新状态
+export const eventRetryCronTime: string = process.env.EVENT_RETRY_CRON_TIME || '30 */5 * * * *'; // 默认每 5 min 执行一次(错开整点避开 iap-reconcile):扫 pending_webhooks>0 的事件兜底投递
 export const quoteCleanupCronTime: string = process.env.QUOTE_CLEANUP_CRON_TIME || '0 0 2 * * *'; // 默认每天凌晨 2 点执行一次
 export const vendorTimeoutMinutes: number = process.env.VENDOR_TIMEOUT_MINUTES
   ? +process.env.VENDOR_TIMEOUT_MINUTES