Iapkit E2E Martie

IAPKit Martie Receipt E2E

Verify the complete mobile purchase-to-local-IAPKit receipt path with the OpenIAP example apps. Do not treat product sync, public-page smoke, or mocked receipts as a substitute for this vertical.

Targets

• OpenIAP repo: $OPENIAP_REPO (the current checkout)
• IAPKit server: $OPENIAP_REPO/packages/kit
• React Native fixture: $OPENIAP_REPO/libraries/react-native-iap/example
• Expo fixture: $OPENIAP_REPO/libraries/expo-iap/example
• App bundle/application id: dev.hyo.martie
• IAPKit project: organization hyo-dev, project martie
• Purchases evidence: the dashboard or Convex Data view backed by the exact Martie Convex deployment used by the local server
• Local receipt endpoint: POST /v1/purchase/verify

Use one example framework and one store per live run. Prefer the already installed, store-compatible example and record which framework, device, and store produced the evidence.

Keep Smoke and Live Receipt Results Separate

Server smoke

Server smoke is safe and does not open a store purchase dialog. It may use the placeholder Convex URL and a synthetic malformed request to prove that the compiled binary boots and routes /v1/purchase/verify through authentication and validation.

Run:

OPENIAP_REPO="${OPENIAP_REPO:-$(git rev-parse --show-toplevel)}"
cd "$OPENIAP_REPO/packages/kit"
bun run typecheck
bun run test
bun run smoke:server

Report this lane only as SMOKE PASS or SMOKE FAIL. A health check, HTTP 400 probe, mocked receipt, or public-page browser check never proves a live receipt.

Live receipt vertical

The live lane purchases a Martie sandbox product on a mobile device, sends the real token or JWS to the locally running compiled IAPKit server, verifies it against the store through the real Martie Convex deployment, and finishes the transaction. Report LIVE RECEIPT PASS only when every assertion below is satisfied.

Safety Gates

• Require explicit user approval for the live sandbox purchase in the current run. Stop immediately before pressing Purchase/Subscribe or confirming the store sheet when that approval has not yet been given. Permission to build, install, launch, fetch products, or run smoke does not authorize a purchase.
• Do not create, reveal, rotate, revoke, or regenerate an IAPKit API key without separate explicit approval. Use an existing Martie project key and redact it from commands, logs, screenshots, and reports.
• Do not create, edit, push, pull, or delete store products as part of this receipt workflow. Store-catalog mutation is a different E2E scope.
• Use sandbox/test accounts only. Do not claim that sandbox means no external side effect; the store still creates purchase/transaction state.
• Never place a sandbox/tester email or password in this skill, repository files, environment files, shell commands, logs, screenshots, or reports. Enter credentials only in Apple's on-device system sign-in UI. Redact the account identity from captured evidence unless the user explicitly needs it.
• Treat signing out of Media & Purchases as a separate, device-wide account change. Do it only for the TestFlight sandbox-controls path on a dedicated test device and only after the user approves that exact change; it can remove access to production purchased content on the device.
• Do not repeatedly retry a rejected account password or an Apple account challenge. Stop as BLOCKED and let the user complete password, verification, terms, or account-recovery prompts directly on the device.
• Prefer a repeatable consumable. Never leave a purchased transaction unfinished merely to preserve test evidence.

Preflight

1. Read $OPENIAP_REPO/AGENTS.md, packages/kit/CONVENTION.md, the selected framework's AGENTS.md, and the Local (IAPKit) Receipt Vertical section of .claude/commands/e2e-tests.md.
2. Run git status --short --branch and preserve all existing changes.
3. Confirm port 3100 is free and identify the device:
   • Android: adb devices -l
   • iOS: xcrun devicectl list devices
4. Classify the iOS app as development-signed or TestFlight and follow Prepare the iOS Sandbox Account. Confirm the device can load the store and install or launch dev.hyo.martie.
5. For Android, follow Prepare the Google Play License Tester and confirm which Google Account the Play purchase sheet will use.
6. Confirm an existing Martie IAPKit API key and the exact Martie Convex deployment that issued it are available. A placeholder or cross-deployment key/URL pair blocks the live lane.
7. Confirm the selected example exposes the distinct Local (Device), Local (IAPKit), IAPKit, and None (Skip) choices in that order, then fetches the Martie catalog before requesting purchase.

Treat a missing device, store account, catalog, API key, real Convex URL, or network route as BLOCKED, not passed.

Prepare the iOS Sandbox Account

Do not treat the TestFlight download account and Sandbox Apple Account as the same role:

• The production Apple Account under Media & Purchases downloads the beta from TestFlight.
• The Sandbox Apple Account attributes test purchases and exposes sandbox controls. TestFlight and development-signed apps both create sandbox transactions, which do not incur charges.

For a development-signed app installed from Xcode, devicectl, React Native, or Expo:

1. Keep the device's production Media & Purchases account signed in.
2. Launch the app and initiate the first purchase only after the live-purchase approval gate.
3. Complete Apple's Sandbox Apple Account sign-in in the on-device purchase flow or under Settings → Developer → Sandbox Apple Account when the option is available.
4. Require Apple's purchase UI to identify the environment as [Environment: Sandbox]. If it does not, cancel and report BLOCKED; never continue against a production environment.

For an app installed from TestFlight:

1. While the production Media & Purchases account is still signed in, download the beta from TestFlight.
2. Obtain explicit approval for the device-wide account change, then open Settings → Apple Account → Media & Purchases and sign out.
3. Open Settings → Developer → Sandbox Apple Account → Sign In and let the user enter the Sandbox Apple Account credentials directly on the device.
4. Keep production Media & Purchases signed out during the sandbox-control run. Signing it back in makes TestFlight purchases use the production Apple Account attribution instead of the Sandbox Apple Account.

If the execution environment cannot control the physical iPhone UI, prepare the installed app and purchase screen, then pause for the user to complete only the system account prompt. Never claim that a CLI install or a known email proves the account is signed in. Follow Apple's current sandbox testing instructions when device labels differ by iOS version.

Prepare the Google Play License Tester

TestFlight and Apple's Sandbox Apple Account do not apply to Android. Google Play needs a Google Account registered under Play Console → Settings → License testing:

1. Confirm the device has an up-to-date Google Play Store and the intended license-tester account. Never store or type its credentials through a shell, repository file, environment file, log, or screenshot.
2. Confirm dev.hyo.martie matches the Play Console application id and that its products are published. A license tester may use a side-loaded debug build; otherwise install the opted-in internal/closed-test build from Play.
3. If the device has multiple Google Accounts, expand the purchase sheet and confirm the selected account. Prefer installing the app from Play with the tester account so Google selects it deterministically.
4. Require the Google purchase sheet to identify the transaction as a test and offer a test payment instrument. If it shows an ordinary payment method or could charge real money, cancel and report BLOCKED.

Follow Google's current Play Billing test instructions when the Play Store UI or tester controls differ.

Make the Local Server Reachable

Build and start the compiled server in a dedicated terminal with the real Martie Convex deployment:

OPENIAP_REPO="${OPENIAP_REPO:-$(git rev-parse --show-toplevel)}"
cd "$OPENIAP_REPO/packages/kit"
: "${CONVEX_URL:?Set the real Martie Convex deployment URL}"
VITE_KIT_CONVEX_URL="$CONVEX_URL" bun run build:all
CONVEX_URL="$CONVEX_URL" \
VITE_KIT_CONVEX_URL="$CONVEX_URL" \
STATIC_ROOT="$PWD/dist" \
PORT=3100 \
KIT_DEBUG_VERIFY_LOGS=1 \
./openiap-kit-server

Verify /health from the host, then verify the same origin from the device or an equivalent device-side network probe.

• Android over USB: inspect the current reverse mappings and reuse an existing tcp:3100 to tcp:3100 mapping. If it is absent, create it and record that this run owns it:

  existing_reverse_rules="$(adb -s "$ANDROID_SERIAL" reverse --list)"
  IAPKIT_REVERSE_BLOCKED=0
  if printf '%s\n' "$existing_reverse_rules" | \
    grep -Eq '(^|[[:space:]])tcp:3100[[:space:]]+tcp:3100($|[[:space:]])'; then
    IAPKIT_REVERSE_CREATED=0
  elif adb -s "$ANDROID_SERIAL" reverse --no-rebind tcp:3100 tcp:3100; then
    IAPKIT_REVERSE_CREATED=1
  else
    IAPKIT_REVERSE_CREATED=0
    IAPKIT_REVERSE_BLOCKED=1
    echo 'BLOCKED: could not create tcp:3100 reverse mapping without rebinding' >&2
  fi
  if [ "$IAPKIT_REVERSE_BLOCKED" != "0" ]; then
    exit 1
  fi

  Keep IAPKIT_REVERSE_CREATED in the shell used for cleanup and configure http://127.0.0.1:3100 in the app. If --no-rebind fails, stop as BLOCKED or select a different free port; never overwrite the existing mapping.

• Physical iPhone: use the Mac's current LAN IP, for example http://192.168.0.4:3100. Device localhost points to the iPhone, not the Mac.

• Android without adb reverse: use the Mac LAN IP and keep both devices on a mutually reachable network.

• Simulator/emulator addresses differ from physical-device addresses. Discover the route instead of copying a stale IP.

The configured base URL is an origin only; do not append /v1/purchase/verify. If HTTP cleartext is blocked in a non-debug build, fix or use the example's intended debug networking configuration rather than claiming the server is unreachable.

Configure and Rebuild One Example

React Native environment:

IAPKIT_API_KEY=<existing Martie project key>
IAPKIT_BASE_URL=<device-reachable local origin>

Expo environment:

EXPO_PUBLIC_IAPKIT_API_KEY=<existing Martie project key>
EXPO_PUBLIC_IAPKIT_BASE_URL=<device-reachable local origin>

Keep secrets in ignored local environment files or the process environment. Rebuild/reinstall the native app after changing these build-time values; do not assume a JavaScript reload changed the native verification payload. Confirm the screen label is Local (IAPKit), not Local (Device) or IAPKit, before purchase.

For the Expo Vega target, bun run build:vega:debug loads the normal Expo development environment-file chain, including ignored .env.local, and embeds only the two EXPO_PUBLIC_* values above. Do not manually print or inspect the generated key value. After building, install with VEGA_DEVICE_ID="$VEGA_DEVICE_ID" bun run run:vega:firetv, then require the same local-server and purchases-view evidence as the other live lanes.