Add CTX gift card purchase paid from an Edge wallet

Orders a card with POST /gift-cards, which allocates a payment address and
quotes the crypto amount, then hands that address and amount to the normal
send flow and polls the card until CTX reports it fulfilled.

The request field names and the order shape are what staging actually
accepts; the placeholder gift card cleaner from the read-only pass was a
guess and is replaced by the real one.

Staging quotes every asset on testnet, so the payment resolves to the one
testnet chain Edge carries a wallet for, sepolia.

Author: j0ntz

CHANGELOG.md

@@ -3,7 +3,7 @@
 ## Unreleased (develop)
 
 - added: App/device attestation for gated info-server requests
-- added: CTX spend-api pubkey auth prototype, with the anonymous session readable from the gift card account info scene
+- added: CTX spend-api prototype, covering the anonymous pubkey session and a gift card purchase paid from an Edge wallet, both driven from the gift card account info scene
 - added: "-m" tag on the version number in the Help scene for Maestro test builds
 - changed: Target Android 16 (API level 36), which Google Play requires for app updates submitted after Aug 30, 2026. Predictive back is opted out of for now, since React Native 0.79 cannot handle it, so the back button behaves exactly as it did before.
 - changed: Style the entire "Already have an account? Sign in" line in the getting-started USP carousel with the tertiary link color, not just "Sign in".

src/__tests__/ctxSpendPurchase.test.ts

@@ -0,0 +1,120 @@
+import { describe, expect, test } from '@jest/globals'
+import type { EdgeCurrencyWallet } from 'edge-core-js'
+
+import {
+  getCtxPaymentNativeAmount,
+  getCtxPaymentPluginId,
+  isCtxGiftCardPaid
+} from '../plugins/gift-cards/ctxSpendPurchase'
+import type { CtxSpendGiftCard } from '../plugins/gift-cards/ctxSpendTypes'
+
+// A card as `POST /gift-cards` actually returns it, trimmed to the fields
+// these helpers read.
+const makeCard = (
+  overrides: Partial<CtxSpendGiftCard> = {}
+): CtxSpendGiftCard => {
+  const card: CtxSpendGiftCard = {
+    id: '2adf8f1c-4885-44e4-a17b-8ae35b9a1bc5',
+    merchantId: '7c8bf315-703f-4b6c-972d-574411c059e9',
+    merchantName: 'Amazon',
+    cardFiatAmount: '0.01',
+    cardFiatCurrency: 'USD',
+    paymentId: '99df9dd3-985f-4fa2-a82e-6074222f92cd',
+    paymentMethod: 'crypto',
+    paymentCryptoAddress: '0x67587B625a63a1E692eb7D73Dc11d57Ff3597406',
+    paymentCryptoAmount: '0.000005200000000000',
+    paymentCryptoChain: 'ETH',
+    paymentCryptoCurrency: 'ETH',
+    paymentCryptoNetwork: 'testnet',
+    paymentUrls: {},
+    rate: '1923.0769',
+    status: 'unpaid',
+    displayStatus: 'unpaid',
+    paymentStatus: 'unpaid',
+    fulfilmentStatus: 'pending',
+    created: '2026-08-17T19:53:14Z',
+    updated: '2026-08-17T19:53:14Z'
+  }
+  return { ...card, ...overrides }
+}
+
+const makeWallet = (multiplier: string): EdgeCurrencyWallet =>
+  ({
+    currencyInfo: { denominations: [{ multiplier }] }
+  } as unknown as EdgeCurrencyWallet)
+
+describe('getCtxPaymentPluginId', () => {
+  test('maps a testnet ETH quote to sepolia, the only testnet Edge carries', () => {
+    expect(getCtxPaymentPluginId(makeCard())).toBe('sepolia')
+  })
+
+  test('maps a mainnet ETH quote to ethereum', () => {
+    expect(
+      getCtxPaymentPluginId(makeCard({ paymentCryptoNetwork: 'mainnet' }))
+    ).toBe('ethereum')
+  })
+
+  test('returns undefined for chains Edge has no wallet type for', () => {
+    // Staging quotes these happily; the app still cannot pay them.
+    for (const chain of ['XMR', 'ZEC', 'ZANO', 'DASH', 'XLM', 'LTC', 'BCH']) {
+      expect(
+        getCtxPaymentPluginId(makeCard({ paymentCryptoChain: chain }))
+      ).toBeUndefined()
+    }
+  })
+
+  test('returns undefined when the quote names no chain or network', () => {
+    expect(
+      getCtxPaymentPluginId(makeCard({ paymentCryptoChain: undefined }))
+    ).toBeUndefined()
+    expect(
+      getCtxPaymentPluginId(makeCard({ paymentCryptoNetwork: undefined }))
+    ).toBeUndefined()
+  })
+})
+
+describe('getCtxPaymentNativeAmount', () => {
+  test('converts the quote to wei exactly', () => {
+    // The payment URI for this same card carries value=5200000000000.
+    expect(
+      getCtxPaymentNativeAmount(makeCard(), makeWallet('1000000000000000000'))
+    ).toBe('5200000000000')
+  })
+
+  test('never rounds down, since an underpayment leaves the card unpaid', () => {
+    // A quote finer than the chain's smallest unit must round up.
+    const card = makeCard({ paymentCryptoAmount: '0.000000015' })
+    expect(getCtxPaymentNativeAmount(card, makeWallet('100000000'))).toBe('2')
+  })
+
+  test('throws when the card carries no payment amount', () => {
+    expect(() =>
+      getCtxPaymentNativeAmount(
+        makeCard({ paymentCryptoAmount: undefined }),
+        makeWallet('1000000000000000000')
+      )
+    ).toThrow()
+  })
+})
+
+describe('isCtxGiftCardPaid', () => {
+  test('a fresh order is not paid', () => {
+    expect(isCtxGiftCardPaid(makeCard())).toBe(false)
+    expect(isCtxGiftCardPaid(makeCard({ paymentStatus: 'pending' }))).toBe(
+      false
+    )
+  })
+
+  test('recognises the paid state staging actually reports', () => {
+    // Observed live: `unpaid` becomes `paid` once the send confirms.
+    expect(isCtxGiftCardPaid(makeCard({ paymentStatus: 'paid' }))).toBe(true)
+  })
+
+  test('an in-progress fulfilment does not make it paid', () => {
+    // `fulfilmentStatus` runs on its own track (`pending`, then `ordered`)
+    // and says nothing about whether the payment landed.
+    expect(isCtxGiftCardPaid(makeCard({ fulfilmentStatus: 'ordered' }))).toBe(
+      false
+    )
+  })
+})