payment-kit 1.27.2 → 1.29.0

package/api/tests/integrations/iap-reconcile.spec.ts

@@ -0,0 +1,237 @@
+/* eslint-disable require-await, import/first */
+// Unit tests for iap-reconcile drift detection.
+//
+// The DB query path (Subscription.findAll + per-row update) is not exercised
+// here — it's a thin loop over the drift functions. Drift detection is the
+// only place where state-machine logic lives, so that's what we test.
+
+const mockCreateEvent: jest.Mock<Promise<undefined>, any[]> = jest.fn(async () => undefined);
+
+jest.mock('../../src/store/models', () => ({
+  Subscription: {},
+  PaymentMethod: {},
+}));
+
+jest.mock('../../src/libs/audit', () => ({
+  createEvent: (...args: any[]) => mockCreateEvent(...args),
+}));
+
+import {
+  applyAppStoreTransactionDrift,
+  applyGooglePlayPurchaseDrift,
+  pickIapMethodForSub,
+} from '../../src/integrations/iap-reconcile';
+import type { AppStoreTransactionPayload } from '../../src/integrations/app-store/client';
+import type { GooglePlaySubscriptionPurchase } from '../../src/integrations/google-play/client';
+
+type SubFake = {
+  id: string;
+  status: string;
+  current_period_end: number;
+  cancel_at_period_end?: boolean;
+  payment_details?: any;
+  metadata?: any;
+  update: jest.Mock;
+};
+
+const makeSub = (overrides: Partial<SubFake> = {}): SubFake => {
+  const sub: SubFake = {
+    id: 'sub_1',
+    status: 'active',
+    current_period_end: Math.floor(Date.now() / 1000) + 30 * 86400, // 30 days out
+    cancel_at_period_end: false,
+    payment_details: { app_store: { original_transaction_id: 'orig_1' } },
+    metadata: {},
+    update: jest.fn(async (patch: any) => Object.assign(sub, patch)) as any,
+    ...overrides,
+  };
+  return sub;
+};
+
+const makeAppStoreTxn = (overrides: Partial<AppStoreTransactionPayload> = {}): AppStoreTransactionPayload =>
+  ({
+    transactionId: 'txn_1',
+    originalTransactionId: 'orig_1',
+    productId: 'pro_monthly',
+    bundleId: 'com.example.app',
+    environment: 'Sandbox',
+    expiresDate: Date.now() + 30 * 86400 * 1000,
+    purchaseDate: Date.now() - 60_000,
+    ...overrides,
+  }) as AppStoreTransactionPayload;
+
+const makeGooglePurchase = (overrides: Partial<GooglePlaySubscriptionPurchase> = {}): GooglePlaySubscriptionPurchase =>
+  ({
+    expiryTimeMillis: String(Date.now() + 30 * 86400 * 1000),
+    autoRenewing: true,
+    ...overrides,
+  }) as GooglePlaySubscriptionPurchase;
+
+beforeEach(() => {
+  mockCreateEvent.mockClear();
+});
+
+describe('pickIapMethodForSub', () => {
+  const m = (id: string) => ({ id }) as any;
+
+  it('selects the method bound via default_payment_method_id', () => {
+    const methods = [m('pm_a'), m('pm_b')];
+    const sub = { id: 's1', default_payment_method_id: 'pm_b' } as any;
+    expect(pickIapMethodForSub(methods, sub)?.id).toBe('pm_b');
+  });
+
+  it('returns undefined (no arbitrary fallback) when bound method is absent and several exist', () => {
+    const methods = [m('pm_a'), m('pm_b')];
+    const sub = { id: 's1', default_payment_method_id: 'pm_missing' } as any;
+    expect(pickIapMethodForSub(methods, sub)).toBeUndefined();
+  });
+
+  it('defaults to the sole method when there is exactly one', () => {
+    const methods = [m('pm_only')];
+    const sub = { id: 's1', default_payment_method_id: undefined } as any;
+    expect(pickIapMethodForSub(methods, sub)?.id).toBe('pm_only');
+  });
+});
+
+describe('applyAppStoreTransactionDrift', () => {
+  it('no-ops when Apple state matches local', async () => {
+    const expires = Math.floor(Date.now() / 1000) + 30 * 86400;
+    const sub = makeSub({ current_period_end: expires });
+    const txn = makeAppStoreTxn({ expiresDate: expires * 1000 });
+
+    const changed = await applyAppStoreTransactionDrift(sub as any, txn);
+    expect(changed).toBe(false);
+    expect(sub.update).not.toHaveBeenCalled();
+  });
+
+  it('updates current_period_end when Apple says we renewed (forward jump)', async () => {
+    const oldExpires = Math.floor(Date.now() / 1000) + 86400; // 1 day out
+    const newExpiresSec = oldExpires + 30 * 86400; // renewed for 30 more days
+    const sub = makeSub({ current_period_end: oldExpires });
+    const txn = makeAppStoreTxn({ expiresDate: newExpiresSec * 1000 });
+
+    const changed = await applyAppStoreTransactionDrift(sub as any, txn);
+    expect(changed).toBe(true);
+    expect(sub.update).toHaveBeenCalledTimes(1);
+    const patch = sub.update.mock.calls[0]![0];
+    expect(patch.current_period_end).toBe(newExpiresSec);
+    expect(patch.status).toBe('active');
+    expect(mockCreateEvent).toHaveBeenCalledWith('Subscription', 'customer.subscription.updated', sub);
+  });
+
+  it('marks canceled when transaction has revocationDate (refund/revoke)', async () => {
+    const sub = makeSub({ status: 'active' });
+    const revocationDate = Date.now() - 60_000;
+    const txn = makeAppStoreTxn({ revocationDate });
+
+    const changed = await applyAppStoreTransactionDrift(sub as any, txn);
+    expect(changed).toBe(true);
+    const patch = sub.update.mock.calls[0]![0];
+    expect(patch.status).toBe('canceled');
+    expect(patch.canceled_at).toBe(Math.floor(revocationDate / 1000));
+    expect(patch.cancelation_details.reason).toBe('app_store_revoked');
+    expect(mockCreateEvent).toHaveBeenCalledWith('Subscription', 'customer.subscription.deleted', sub);
+  });
+
+  it('idempotent: does not re-cancel already-canceled subscription', async () => {
+    const sub = makeSub({ status: 'canceled' });
+    const txn = makeAppStoreTxn({ revocationDate: Date.now() - 60_000 });
+
+    const changed = await applyAppStoreTransactionDrift(sub as any, txn);
+    expect(changed).toBe(false);
+    expect(sub.update).not.toHaveBeenCalled();
+  });
+
+  it('marks canceled when Apple says expired but local still active (webhook miss on EXPIRED)', async () => {
+    const expiredSec = Math.floor(Date.now() / 1000) - 3600; // 1h in the past
+    const sub = makeSub({ status: 'active', current_period_end: expiredSec });
+    const txn = makeAppStoreTxn({ expiresDate: expiredSec * 1000 });
+
+    const changed = await applyAppStoreTransactionDrift(sub as any, txn);
+    expect(changed).toBe(true);
+    const patch = sub.update.mock.calls[0]![0];
+    expect(patch.status).toBe('canceled');
+    expect(patch.cancelation_details.reason).toBe('app_store_expired');
+  });
+});
+
+describe('applyGooglePlayPurchaseDrift', () => {
+  it('no-ops when Google state matches local', async () => {
+    const expires = Math.floor(Date.now() / 1000) + 30 * 86400;
+    const sub = makeSub({
+      current_period_end: expires,
+      payment_details: { google_play: { purchase_token: 'tok_1' } },
+    });
+    const purchase = makeGooglePurchase({ expiryTimeMillis: String(expires * 1000) });
+
+    const changed = await applyGooglePlayPurchaseDrift(sub as any, purchase);
+    expect(changed).toBe(false);
+    expect(sub.update).not.toHaveBeenCalled();
+  });
+
+  it('updates current_period_end when Google says we renewed', async () => {
+    const oldExpires = Math.floor(Date.now() / 1000) + 86400;
+    const newExpiresSec = oldExpires + 30 * 86400;
+    const sub = makeSub({
+      current_period_end: oldExpires,
+      payment_details: { google_play: { purchase_token: 'tok_1' } },
+    });
+    const purchase = makeGooglePurchase({ expiryTimeMillis: String(newExpiresSec * 1000) });
+
+    const changed = await applyGooglePlayPurchaseDrift(sub as any, purchase);
+    expect(changed).toBe(true);
+    const patch = sub.update.mock.calls[0]![0];
+    expect(patch.current_period_end).toBe(newExpiresSec);
+    expect(mockCreateEvent).toHaveBeenCalledWith('Subscription', 'customer.subscription.updated', sub);
+  });
+
+  it('sets cancel_at_period_end when user disabled auto-renew (cancelReason set, autoRenewing=false)', async () => {
+    const sub = makeSub({
+      cancel_at_period_end: false,
+      payment_details: { google_play: { purchase_token: 'tok_1' } },
+    });
+    const purchase = makeGooglePurchase({
+      expiryTimeMillis: String(sub.current_period_end * 1000), // not a renewal drift
+      cancelReason: 0,
+      autoRenewing: false,
+    });
+
+    const changed = await applyGooglePlayPurchaseDrift(sub as any, purchase);
+    expect(changed).toBe(true);
+    const patch = sub.update.mock.calls[0]![0];
+    expect(patch.cancel_at_period_end).toBe(true);
+    expect(patch.cancelation_details.reason).toBe('google_play_auto_renew_off');
+  });
+
+  it('idempotent: does not re-flag cancel_at_period_end when already set', async () => {
+    const sub = makeSub({
+      cancel_at_period_end: true,
+      payment_details: { google_play: { purchase_token: 'tok_1' } },
+    });
+    const purchase = makeGooglePurchase({
+      expiryTimeMillis: String(sub.current_period_end * 1000),
+      cancelReason: 0,
+      autoRenewing: false,
+    });
+
+    const changed = await applyGooglePlayPurchaseDrift(sub as any, purchase);
+    expect(changed).toBe(false);
+    expect(sub.update).not.toHaveBeenCalled();
+  });
+
+  it('marks canceled when Google says expired but local still active', async () => {
+    const expiredSec = Math.floor(Date.now() / 1000) - 3600;
+    const sub = makeSub({
+      status: 'active',
+      current_period_end: expiredSec,
+      payment_details: { google_play: { purchase_token: 'tok_1' } },
+    });
+    const purchase = makeGooglePurchase({ expiryTimeMillis: String(expiredSec * 1000) });
+
+    const changed = await applyGooglePlayPurchaseDrift(sub as any, purchase);
+    expect(changed).toBe(true);
+    const patch = sub.update.mock.calls[0]![0];
+    expect(patch.status).toBe('canceled');
+    expect(patch.cancelation_details.reason).toBe('google_play_expired');
+  });
+});

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

@@ -0,0 +1,347 @@
+/* eslint-disable require-await, import/first */
+// Unit tests for libs/entitlement.ts — cross-channel entitlement check.
+// Models are mocked; DB is not touched.
+
+import { checkEntitlement, listEntitlements } from '../../src/libs/entitlement';
+
+const mockCustomerFindOne: jest.Mock<any, any[]> = jest.fn();
+const mockSubscriptionFindAll: jest.Mock<any, any[]> = jest.fn();
+const mockCreditGrantFindAll: jest.Mock<any, any[]> = jest.fn();
+const mockPaymentMethodFindByPk: jest.Mock<any, any[]> = jest.fn();
+const mockPriceFindAll: jest.Mock<any, any[]> = jest.fn();
+
+jest.mock('../../src/store/models', () => ({
+  Customer: { findOne: (...args: any[]) => mockCustomerFindOne(...args) },
+  Subscription: { findAll: (...args: any[]) => mockSubscriptionFindAll(...args) },
+  SubscriptionItem: {},
+  Price: { findAll: (...args: any[]) => mockPriceFindAll(...args) },
+  Product: {},
+  CreditGrant: { findAll: (...args: any[]) => mockCreditGrantFindAll(...args) },
+  PaymentMethod: { findByPk: (...args: any[]) => mockPaymentMethodFindByPk(...args) },
+}));
+
+const makeSub = (overrides: Record<string, any> = {}) => ({
+  id: 'sub_1',
+  status: 'active',
+  channel: 'app_store',
+  current_period_end: Math.floor(Date.now() / 1000) + 30 * 86400,
+  default_payment_method_id: 'pm_1',
+  items: [{ price: { product_id: 'pro_monthly' } }],
+  ...overrides,
+});
+
+const makeGrant = (overrides: Record<string, any> = {}) => ({
+  id: 'cg_1',
+  customer_id: 'cus_1',
+  status: 'granted',
+  remaining_amount: '100',
+  expires_at: Math.floor(Date.now() / 1000) + 30 * 86400,
+  metadata: { product_id: 'one_off_product', payment_method_id: 'pm_stripe' },
+  ...overrides,
+});
+
+beforeEach(() => {
+  mockCustomerFindOne.mockReset();
+  mockSubscriptionFindAll.mockReset().mockResolvedValue([]);
+  mockCreditGrantFindAll.mockReset().mockResolvedValue([]);
+  mockPaymentMethodFindByPk.mockReset();
+  mockPriceFindAll.mockReset().mockResolvedValue([]);
+});
+
+describe('checkEntitlement', () => {
+  it('returns inactive when customer not found', async () => {
+    mockCustomerFindOne.mockResolvedValue(null);
+    const result = await checkEntitlement({ customer_did: 'did:unknown', product_id: 'pro_monthly' });
+    expect(result).toEqual({
+      active: false,
+      channel: null,
+      expires_at: null,
+      subscription_id: null,
+      source: null,
+    });
+    expect(mockSubscriptionFindAll).not.toHaveBeenCalled();
+  });
+
+  it('returns active result for active subscription', async () => {
+    mockCustomerFindOne.mockResolvedValue({ id: 'cus_1' });
+    mockSubscriptionFindAll.mockResolvedValue([makeSub()]);
+
+    const result = await checkEntitlement({ customer_did: 'did:1', product_id: 'pro_monthly' });
+    expect(result.active).toBe(true);
+    expect(result.subscription_id).toBe('sub_1');
+    expect(result.channel).toBe('app_store');
+    expect(result.source).toBe('subscription');
+  });
+
+  it('returns inactive=true subscription_id set for past_due (covers grace period)', async () => {
+    mockCustomerFindOne.mockResolvedValue({ id: 'cus_1' });
+    mockSubscriptionFindAll.mockResolvedValue([makeSub({ status: 'past_due' })]);
+
+    const result = await checkEntitlement({ customer_did: 'did:1', product_id: 'pro_monthly' });
+    expect(result.active).toBe(false);
+    expect(result.subscription_id).toBe('sub_1');
+    expect(result.source).toBe('subscription');
+  });
+
+  it('picks active over trialing over paused when multiple subs cover the same product', async () => {
+    mockCustomerFindOne.mockResolvedValue({ id: 'cus_1' });
+    mockSubscriptionFindAll.mockResolvedValue([
+      makeSub({ id: 'sub_paused', status: 'paused' }),
+      makeSub({ id: 'sub_active', status: 'active' }),
+      makeSub({ id: 'sub_trial', status: 'trialing' }),
+    ]);
+
+    const result = await checkEntitlement({ customer_did: 'did:1', product_id: 'pro_monthly' });
+    expect(result.subscription_id).toBe('sub_active');
+    expect(result.active).toBe(true);
+  });
+
+  it('breaks ties on equal status by latest current_period_end', async () => {
+    mockCustomerFindOne.mockResolvedValue({ id: 'cus_1' });
+    mockSubscriptionFindAll.mockResolvedValue([
+      makeSub({ id: 'sub_older', status: 'active', current_period_end: 1700000000 }),
+      makeSub({ id: 'sub_newer', status: 'active', current_period_end: 1800000000 }),
+    ]);
+
+    const result = await checkEntitlement({ customer_did: 'did:1', product_id: 'pro_monthly' });
+    expect(result.subscription_id).toBe('sub_newer');
+  });
+
+  it('skips subscriptions whose items do not cover the target product', async () => {
+    mockCustomerFindOne.mockResolvedValue({ id: 'cus_1' });
+    mockSubscriptionFindAll.mockResolvedValue([makeSub({ items: [{ price: { product_id: 'other_product' } }] })]);
+    mockCreditGrantFindAll.mockResolvedValue([]);
+
+    const result = await checkEntitlement({ customer_did: 'did:1', product_id: 'pro_monthly' });
+    expect(result.active).toBe(false);
+    expect(result.subscription_id).toBeNull();
+  });
+
+  it('resolves IAP subscription live via Product channel mapping (no items, empty metadata.product_id)', async () => {
+    // Mirrors the real app_store case: subscription has no SubscriptionItems and
+    // an empty metadata.product_id (Product mapping was added after purchase),
+    // but reliably stores the channel SKU + bundle_id in payment_details.app_store.
+    mockCustomerFindOne.mockResolvedValue({ id: 'cus_1' });
+    mockSubscriptionFindAll.mockResolvedValue([
+      makeSub({
+        id: 'sub_iap',
+        channel: 'app_store',
+        items: [],
+        metadata: {},
+        payment_details: { app_store: { product_id: 'pk_demo_monthly', bundle_id: 'com.example.app' } },
+      }),
+    ]);
+    // Querying the local Product id; its Price.metadata maps to the App Store SKU
+    // (Stripe-style — SKU binding lives on Price, not Product). Multi-tenant:
+    // bundle_id is part of the lookup key so two apps with the same SKU string
+    // don't collide.
+    mockPriceFindAll.mockResolvedValue([
+      { product_id: 'prod_X', metadata: { app_store_product_id: 'pk_demo_monthly', bundle_id: 'com.example.app' } },
+    ]);
+
+    const result = await checkEntitlement({ customer_did: 'did:1', product_id: 'prod_X' });
+    expect(result.active).toBe(true);
+    expect(result.subscription_id).toBe('sub_iap');
+    expect(result.source).toBe('subscription');
+  });
+
+  it('does NOT match when the Price channel SKU differs from the subscription SKU', async () => {
+    mockCustomerFindOne.mockResolvedValue({ id: 'cus_1' });
+    mockSubscriptionFindAll.mockResolvedValue([
+      makeSub({
+        id: 'sub_iap',
+        items: [],
+        metadata: {},
+        payment_details: { app_store: { product_id: 'pk_demo_monthly', bundle_id: 'com.example.app' } },
+      }),
+    ]);
+    mockPriceFindAll.mockResolvedValue([
+      { product_id: 'prod_Y', metadata: { app_store_product_id: 'pk_other_sku', bundle_id: 'com.example.app' } },
+    ]);
+
+    const result = await checkEntitlement({ customer_did: 'did:1', product_id: 'prod_Y' });
+    expect(result.active).toBe(false);
+    expect(result.subscription_id).toBeNull();
+  });
+
+  it('IAP SKU rebind does not double-grant — live mapping wins over a stale SubscriptionItem', async () => {
+    mockCustomerFindOne.mockResolvedValue({ id: 'cus_1' });
+    // app_store sub: stale item points to prod_A, but the stored channel SKU is 'sku1'.
+    mockSubscriptionFindAll.mockResolvedValue([
+      makeSub({
+        channel: 'app_store',
+        items: [{ price: { product_id: 'prod_A' } }],
+        payment_details: { app_store: { product_id: 'sku1', bundle_id: 'com.example.app' } },
+      }),
+    ]);
+
+    // Query prod_A: no Price for it bound to sku1 → must be inactive (stale
+    // item ignored).
+    mockPriceFindAll.mockResolvedValue([
+      { product_id: 'prod_A', metadata: { app_store_product_id: 'other_sku', bundle_id: 'com.example.app' } },
+    ]);
+    const a = await checkEntitlement({ customer_did: 'did:1', product_id: 'prod_A' });
+    expect(a.active).toBe(false);
+    expect(a.subscription_id).toBeNull();
+
+    // Query prod_B: a Price under prod_B is now bound to sku1 → active via
+    // live mapping.
+    mockPriceFindAll.mockResolvedValue([
+      { product_id: 'prod_B', metadata: { app_store_product_id: 'sku1', bundle_id: 'com.example.app' } },
+    ]);
+    const b = await checkEntitlement({ customer_did: 'did:1', product_id: 'prod_B' });
+    expect(b.active).toBe(true);
+    expect(b.subscription_id).toBe('sub_1');
+  });
+
+  it('falls back to PaymentMethod.type when Subscription.channel is unset', async () => {
+    mockCustomerFindOne.mockResolvedValue({ id: 'cus_1' });
+    mockSubscriptionFindAll.mockResolvedValue([makeSub({ channel: undefined })]);
+    mockPaymentMethodFindByPk.mockResolvedValue({ type: 'stripe' });
+
+    const result = await checkEntitlement({ customer_did: 'did:1', product_id: 'pro_monthly' });
+    expect(result.channel).toBe('stripe');
+  });
+
+  it('falls back to CreditGrant when no subscription matches', async () => {
+    mockCustomerFindOne.mockResolvedValue({ id: 'cus_1' });
+    mockSubscriptionFindAll.mockResolvedValue([]);
+    mockCreditGrantFindAll.mockResolvedValue([makeGrant({ metadata: { product_id: 'pro_monthly' } })]);
+    mockPaymentMethodFindByPk.mockResolvedValue({ type: 'stripe' });
+
+    const result = await checkEntitlement({ customer_did: 'did:1', product_id: 'pro_monthly' });
+    expect(result.active).toBe(true);
+    expect(result.source).toBe('one_time');
+    expect(result.credit_remaining).toBe('100');
+  });
+
+  it('CreditGrant with remaining_amount=0 is inactive', async () => {
+    mockCustomerFindOne.mockResolvedValue({ id: 'cus_1' });
+    mockSubscriptionFindAll.mockResolvedValue([]);
+    mockCreditGrantFindAll.mockResolvedValue([
+      makeGrant({ metadata: { product_id: 'pro_monthly' }, remaining_amount: '0' }),
+    ]);
+
+    const result = await checkEntitlement({ customer_did: 'did:1', product_id: 'pro_monthly' });
+    expect(result.active).toBe(false);
+    expect(result.source).toBe('one_time');
+  });
+
+  it('CreditGrant past expires_at is inactive', async () => {
+    mockCustomerFindOne.mockResolvedValue({ id: 'cus_1' });
+    mockSubscriptionFindAll.mockResolvedValue([]);
+    mockCreditGrantFindAll.mockResolvedValue([
+      makeGrant({ metadata: { product_id: 'pro_monthly' }, expires_at: 1000 }),
+    ]);
+
+    const result = await checkEntitlement({ customer_did: 'did:1', product_id: 'pro_monthly' });
+    expect(result.active).toBe(false);
+  });
+});
+
+describe('listEntitlements', () => {
+  it('returns [] when customer not found', async () => {
+    mockCustomerFindOne.mockResolvedValue(null);
+    expect(await listEntitlements({ customer_did: 'did:unknown' })).toEqual([]);
+  });
+
+  it('returns one row per distinct product, picking best subscription', async () => {
+    mockCustomerFindOne.mockResolvedValue({ id: 'cus_1' });
+    mockSubscriptionFindAll.mockResolvedValue([
+      makeSub({
+        id: 'sub_pro',
+        status: 'active',
+        items: [{ price: { product_id: 'pro_monthly' } }],
+      }),
+      makeSub({
+        id: 'sub_paused_pro',
+        status: 'paused',
+        items: [{ price: { product_id: 'pro_monthly' } }],
+      }),
+      makeSub({
+        id: 'sub_basic',
+        status: 'trialing',
+        items: [{ price: { product_id: 'basic' } }],
+      }),
+    ]);
+
+    const list = await listEntitlements({ customer_did: 'did:1' });
+    expect(list).toHaveLength(2);
+    const pro = list.find((x) => x.product_id === 'pro_monthly');
+    expect(pro?.subscription_id).toBe('sub_pro');
+    const basic = list.find((x) => x.product_id === 'basic');
+    expect(basic?.subscription_id).toBe('sub_basic');
+  });
+
+  it('merges CreditGrant entitlements for products not covered by subscriptions', async () => {
+    mockCustomerFindOne.mockResolvedValue({ id: 'cus_1' });
+    mockSubscriptionFindAll.mockResolvedValue([
+      makeSub({ id: 'sub_pro', items: [{ price: { product_id: 'pro_monthly' } }] }),
+    ]);
+    mockCreditGrantFindAll.mockResolvedValue([
+      makeGrant({ metadata: { product_id: 'one_off' } }),
+      // Already covered by subscription — should NOT duplicate
+      makeGrant({ id: 'cg_dup', metadata: { product_id: 'pro_monthly' } }),
+    ]);
+    mockPaymentMethodFindByPk.mockResolvedValue({ type: 'stripe' });
+
+    const list = await listEntitlements({ customer_did: 'did:1' });
+    expect(list).toHaveLength(2);
+    const oneOff = list.find((x) => x.source === 'one_time');
+    expect(oneOff?.product_id).toBe('one_off');
+    expect(oneOff?.active).toBe(true);
+  });
+
+  it('lists an IAP subscription under its live-mapped product, not a stale item', async () => {
+    mockCustomerFindOne.mockResolvedValue({ id: 'cus_1' });
+    mockSubscriptionFindAll.mockResolvedValue([
+      makeSub({
+        channel: 'app_store',
+        items: [{ price: { product_id: 'prod_A_stale' } }],
+        payment_details: { app_store: { product_id: 'sku1', bundle_id: 'com.example.app' } },
+      }),
+    ]);
+    // Live catalogue: a Price under prod_B is bound to sku1.
+    mockPriceFindAll.mockResolvedValue([
+      { product_id: 'prod_B', metadata: { app_store_product_id: 'sku1', bundle_id: 'com.example.app' } },
+    ]);
+
+    const list = await listEntitlements({ customer_did: 'did:1' });
+    expect(list).toHaveLength(1);
+    expect(list[0]!.product_id).toBe('prod_B');
+  });
+
+  it('multi-tenant: same SKU string across two apps does not grant the wrong product (entitlement leak)', async () => {
+    // Two iOS apps, both legitimately using SKU 'pro_monthly' in their own
+    // App Store Connect namespaces (Apple SKUs are per-bundle-id, not global).
+    // App A's customer has a sub for App A's pro_monthly; App B has its own
+    // distinct Product/Price. Without (sku, bundle_id) scoping in entitlement.ts,
+    // App A's sub would incorrectly grant App B's product too.
+    mockCustomerFindOne.mockResolvedValue({ id: 'cus_appA_user' });
+    mockSubscriptionFindAll.mockResolvedValue([
+      makeSub({
+        channel: 'app_store',
+        items: [],
+        metadata: {},
+        payment_details: { app_store: { product_id: 'pro_monthly', bundle_id: 'com.appA' } },
+      }),
+    ]);
+    // Querying App B's Product, whose Price uses the same SKU string under a
+    // different bundle_id — must NOT match App A's sub.
+    mockPriceFindAll.mockResolvedValue([
+      { product_id: 'prod_appB_pro', metadata: { app_store_product_id: 'pro_monthly', bundle_id: 'com.appB' } },
+    ]);
+
+    const result = await checkEntitlement({ customer_did: 'did:1', product_id: 'prod_appB_pro' });
+    expect(result.active).toBe(false);
+    expect(result.subscription_id).toBeNull();
+  });
+
+  it('skips CreditGrants without product_id metadata', async () => {
+    mockCustomerFindOne.mockResolvedValue({ id: 'cus_1' });
+    mockSubscriptionFindAll.mockResolvedValue([]);
+    mockCreditGrantFindAll.mockResolvedValue([makeGrant({ metadata: {} })]);
+
+    expect(await listEntitlements({ customer_did: 'did:1' })).toEqual([]);
+  });
+});

package/api/tests/libs/wallet-migration.spec.ts

@@ -79,7 +79,7 @@ describe('wallet-migration', () => {
 
     it('should return stored address if available and valid', async () => {
       const mockClient = createMockClient({
-        getDelegateState: jest.fn().mockImplementation(({ address }) => {
+        getDelegateState: jest.fn().mockImplementation(async ({ address }) => {
           if (address === 'stored_delegation_address') {
             return { state: { ops: [{ key: 'fg:x:transfer' }] } };
           }
@@ -105,7 +105,7 @@ describe('wallet-migration', () => {
     it('should fallback if stored address has no valid state', async () => {
       const oldAddress = toDelegateAddress(delegator, oldAppDid);
       const mockClient = createMockClient({
-        getDelegateState: jest.fn().mockImplementation(({ address }) => {
+        getDelegateState: jest.fn().mockImplementation(async ({ address }) => {
           // stored address has no state, but migratedFrom address has
           if (address === oldAddress) {
             return { state: { ops: [{ key: 'fg:x:transfer' }] } };
@@ -131,7 +131,7 @@ describe('wallet-migration', () => {
     it('should return current address if delegation exists on current wallet', async () => {
       const currentAddress = toDelegateAddress(delegator, currentWalletAddress);
       const mockClient = createMockClient({
-        getDelegateState: jest.fn().mockImplementation(({ address }) => {
+        getDelegateState: jest.fn().mockImplementation(async ({ address }) => {
           if (address === currentAddress) {
             return { state: { ops: [{ key: 'fg:x:transfer' }] } };
           }
@@ -154,7 +154,7 @@ describe('wallet-migration', () => {
     it('should fallback to migratedFrom addresses', async () => {
       const oldAddress = toDelegateAddress(delegator, oldAppDid);
       const mockClient = createMockClient({
-        getDelegateState: jest.fn().mockImplementation(({ address }) => {
+        getDelegateState: jest.fn().mockImplementation(async ({ address }) => {
           if (address === oldAddress) {
             return { state: { ops: [{ key: 'fg:x:transfer' }] } };
           }

package/api/tests/queues/credit-consume-batch.spec.ts

@@ -248,13 +248,16 @@ describe('credit-consume: handleBatchCreditConsumption', () => {
     expect(event1.update).toHaveBeenCalledWith(expect.objectContaining({ status: 'completed' }));
 
     // Event 2 should fail — only 20 remaining but needs 80
-    // It should have partial consumption saved and be marked for retry
+    // Partial consumption is saved and event leaves the retry chain immediately
+    // (Insufficient balance is non-retryable per Plan 3, 2026-04-25 — retry
+    // would only re-trip the same shortage until external credit top-up).
     expect(event2.update).toHaveBeenCalledWith(
       expect.objectContaining({
         credit_pending: expect.any(String),
       })
     );
-    expect(event2.markAsRequiresCapture).toHaveBeenCalled();
+    expect(event2.markAsRequiresAction).toHaveBeenCalled();
+    expect(event2.markAsRequiresCapture).not.toHaveBeenCalled();
 
     expect(getLock().release).toHaveBeenCalled();
   });

package/api/tests/queues/credit-consume.spec.ts

@@ -386,7 +386,11 @@ describe('credit-consume: handleCreditConsumption', () => {
   // ==========================================
   // Scenario 22/23: Retry scheduling + max retries
   // ==========================================
-  it('scenario 22: schedules retry on partial failure', async () => {
+  it('scenario 22: insufficient balance is non-retryable (goes straight to requires_action)', async () => {
+    // Insufficient credit balance only resolves via external top-up; retrying
+    // before that is guaranteed to fail again. Per Plan 3 (2026-04-25), this
+    // is classified as non-retryable so the event leaves the retry chain
+    // immediately rather than spawning N more delayed queue messages.
     const event = makeMeterEvent({
       getValue: jest.fn().mockReturnValue('500'),
       attempt_count: 0,
@@ -397,10 +401,10 @@ describe('credit-consume: handleCreditConsumption', () => {
 
     setupBasicMocks(event, meter, customer, [grant]);
 
-    await expect(handleCreditConsumption({ meterEventId: 'me_1' })).rejects.toThrow();
+    await expect(handleCreditConsumption({ meterEventId: 'me_1' })).rejects.toThrow(/Insufficient credit balance/);
 
-    // Should schedule retry (attempt_count=0 < MAX_RETRY_COUNT=3)
-    expect(event.markAsRequiresCapture).toHaveBeenCalled();
+    expect(event.markAsRequiresAction).toHaveBeenCalled();
+    expect(event.markAsRequiresCapture).not.toHaveBeenCalled();
   });
 
   it('scenario 23: marks as requires_action after max retries', async () => {

package/api/tests/routes/credit-grants.spec.ts

@@ -92,6 +92,7 @@ describe('GET /api/credit-grants/verify-availability', () => {
     it('should return 404 if customer not found', async () => {
       if (!routeHandler) return;
       jest.spyOn(Customer, 'findByPkOrDid').mockResolvedValue(null as any);
+      jest.spyOn(PaymentCurrency, 'findByPk').mockResolvedValue({ id: 'currency_123' } as any);
 
       await routeHandler(mockReq as Request, mockRes as Response);