diff --git a/.ai/specs/SPEC-003-2026-02-10-expo-config-plugin-contract.md b/.ai/specs/SPEC-003-2026-02-10-expo-config-plugin-contract.md index 969e964..ad314aa 100644 --- a/.ai/specs/SPEC-003-2026-02-10-expo-config-plugin-contract.md +++ b/.ai/specs/SPEC-003-2026-02-10-expo-config-plugin-contract.md @@ -14,7 +14,7 @@ Define a clear contract for plugin inputs and native modifications: - Plugin entrypoint composes iOS and Android plugin steps. - iOS step adds merchant identifiers to entitlements when configured. -- Android step toggles Google Pay metadata in main application manifest. +- Android step adds or removes Google Pay metadata in the main application manifest when `enableGooglePay` is set, and leaves it alone otherwise. ## Architecture @@ -27,8 +27,8 @@ Source files: Execution model: -1. Expo prebuild runs plugin with user props. -2. `withGooglePay` mutates Android manifest metadata. +1. Expo prebuild runs plugin with user props. A plugin listed without options gets `undefined`; the entrypoint (`index.ts`) defaults it to `{}`, so `withGooglePay` and `withApplePay` always receive an object. +2. `withGooglePay` mutates Android manifest metadata if `enableGooglePay` is set. 3. `withApplePay` mutates iOS entitlements if merchant IDs provided. 4. Native project files generated by Expo include required capability flags. @@ -45,17 +45,19 @@ interface ReactNativePayPluginProps { Normalized behavior: -- `merchantIdentifier` accepts string or array; internal logic normalizes to array. +- Both props are optional, and so is the options object itself. +- `merchantIdentifier` accepts string or array; `withApplePay` normalizes it once to an array without empty values. - Duplicate merchant IDs are not re-added. -- `enableGooglePay` defaults to `false`. +- `enableGooglePay` has no default: `true`, `false` and omitted are three different instructions (see the Android contract). ## API Contracts ### iOS Contract (`withApplePay`) -- If `merchantIdentifier` is missing, no entitlement mutation is performed. +- If `merchantIdentifier` is missing or has no non-empty IDs, no entitlement mutation is performed. - If provided, values are added to `com.apple.developer.in-app-payments`. - Existing entitlement values are preserved and extended. +- An ID that does not start with `merchant.` adds a prebuild warning (`WarningAggregator.addWarningIOS`) and is still added. ### Android Contract (`withGooglePay`) @@ -63,6 +65,7 @@ Normalized behavior: - name: `com.google.android.gms.wallet.api.enabled` - value: `true` - When `enableGooglePay=false`, remove that metadata from main application. +- When `enableGooglePay` is omitted (or `null`), do not touch the manifest, so an entry added by another plugin (Stripe, for example) or by the project stays. ## UI/UX @@ -72,6 +75,8 @@ Not applicable (build-time configuration only). Supported user config examples: +- No options (changes nothing): + - `"@gmisoftware/react-native-pay"` - Apple Pay only: - `{ merchantIdentifier: "merchant.com.example.app" }` - Google Pay only: @@ -93,6 +98,10 @@ Expected consumer workflow: - Rejected to avoid forcing config for apps that do not use Google Pay. 3. **Throw on missing merchant identifier** - Rejected because Android-only apps should be valid. +4. **Default `enableGooglePay` to `false`** + - Replaced on 2026-10-27: removing the entry whenever the option was omitted deleted entries added by other plugins. +5. **Throw on a merchant identifier without the `merchant.` prefix** + - Rejected in favor of a warning, so a prebuild that worked before keeps working. ## Implementation Approach @@ -107,6 +116,12 @@ When changing plugin behavior: No migration required for initial baseline documentation. +2026-10-27 (`enableGooglePay` no longer defaults to `false`): + +- Backward compatibility impact: apps that omitted `enableGooglePay` and relied on the plugin removing `com.google.android.gms.wallet.api.enabled` now keep that entry. +- Required app config updates: set `enableGooglePay: false` to keep removing it. Other configs need no change. +- Prebuild regeneration guidance: run `npx expo prebuild --clean`. + Future plugin contract changes must include: - Backward compatibility impact @@ -121,11 +136,16 @@ Future plugin contract changes must include: ## Open Questions -- Should plugin validate merchant identifier format and warn early? - Should Google Pay metadata support custom boolean value typing beyond string `"true"`? ## Changelog +### 2026-10-27 + +- The plugin runs when listed without options: the entrypoint defaults `undefined` props to `{}`. Previously prebuild failed with `Cannot read properties of undefined (reading 'enableGooglePay')`. +- `enableGooglePay` is tri-state. Previous behavior: omitted meant `false` and removed the Google Pay metadata. New behavior: omitted (or `null`) leaves the manifest untouched. +- `withApplePay` warns about merchant IDs without the `merchant.` prefix, which resolves the open question about validating them. + ### 2026-02-10 - Initial contract for Expo plugin behavior, inputs, and native mutations. diff --git a/CHANGELOG.md b/CHANGELOG.md index 99627e3..22b19eb 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -144,6 +144,14 @@ All notable changes to this project are documented in this file. ### Fixed +- **Expo plugin: works without options and keeps an existing Google Pay manifest entry.** Listing + `"@gmisoftware/react-native-pay"` without an options object crashed `expo prebuild` with + `Cannot read properties of undefined (reading 'enableGooglePay')`. When `enableGooglePay` was + omitted, the plugin also removed `com.google.android.gms.wallet.api.enabled` from the Android + manifest, even if another plugin, such as Stripe's, had added it. The plugin now adds the entry + when `enableGooglePay` is `true`, removes it when it is `false`, and leaves the manifest alone + when it is omitted. Prebuild also warns when a `merchantIdentifier` does not start with + `merchant.`. - **iOS: `ApplePayButton` keeps its `PKPaymentButton` across re-renders.** Every prop update removed the button and created a new one, so an `onPress` with a new identity on each render rebuilt it on every parent re-render. It is now rebuilt only when `buttonType` or `buttonStyle` diff --git a/docs/docs/compatibility.md b/docs/docs/compatibility.md index 98ca254..401fcd9 100644 --- a/docs/docs/compatibility.md +++ b/docs/docs/compatibility.md @@ -20,7 +20,7 @@ Install the correct Nitro version first; the payment library depends on it. ## Expo plugin behavior - **merchantIdentifier** — Optional in the plugin config. If omitted, Apple Pay entitlements are not added (use for Android-only or when you add Apple Pay later). -- **enableGooglePay** — Defaults to **false**. Set to **true** to enable Google Pay on Android. +- **enableGooglePay** — Optional. Set to **true** to enable Google Pay on Android, or **false** to remove the Google Pay manifest entry. If omitted, the plugin leaves the Android manifest as it is. ## Platform support @@ -56,7 +56,7 @@ Use `Platform.OS` (or equivalent) to render the correct button and to pass platf No. The library works in bare React Native too. The Expo plugin only simplifies adding Apple Pay entitlements and Google Pay metadata; in a bare project you configure those in Xcode and Android Studio yourself. **Can I use only Apple Pay or only Google Pay?** -Yes. Omit `enableGooglePay` (or set false) for iOS-only; omit plugin `merchantIdentifier` for Android-only. In code, only render the button for the platform you support. +Yes. Omit `enableGooglePay` for iOS-only (`false` removes an entry another plugin added); omit plugin `merchantIdentifier` for Android-only. In code, only render the button for the platform you support. **Which gateways are supported for Google Pay?** Any gateway that supports the [Google Pay API](https://developers.google.com/pay/api/android) and the gateway token format. Commonly used: Stripe, Braintree, Square, Adyen, Authorize.net, Checkout.com. Set `googlePayMerchantId`, `googlePayGateway`, and `googlePayGatewayMerchantId` accordingly. diff --git a/docs/docs/setup/expo-plugin.md b/docs/docs/setup/expo-plugin.md index aa75e52..0aee14e 100644 --- a/docs/docs/setup/expo-plugin.md +++ b/docs/docs/setup/expo-plugin.md @@ -24,10 +24,12 @@ Add the plugin to `app.json` or `app.config.js`: ## Options +Both options are optional. Listed without options (`"plugins": ["@gmisoftware/react-native-pay"]`), the plugin changes nothing. + | Option | Type | Description | |--------|------|-------------| -| `merchantIdentifier` | `string` or `string[]` | Apple Pay Merchant ID(s). If omitted, Apple Pay entitlements are not added. | -| `enableGooglePay` | `boolean` | If `true`, adds the Google Pay metadata to the Android manifest. Default: `false`. | +| `merchantIdentifier` | `string` or `string[]` | Apple Pay Merchant ID(s). If omitted, Apple Pay entitlements are not added. Each ID should start with `merchant.`; prebuild warns when one does not. | +| `enableGooglePay` | `boolean` | `true` adds the Google Pay metadata (`com.google.android.gms.wallet.api.enabled`) to the Android manifest. `false` removes it. If omitted, the manifest is left as it is, so an entry added by another plugin (Stripe, for example) stays. | ## Examples diff --git a/package/src/plugin/__tests__/index.integration.test.ts b/package/src/plugin/__tests__/index.integration.test.ts new file mode 100644 index 0000000..09acca9 --- /dev/null +++ b/package/src/plugin/__tests__/index.integration.test.ts @@ -0,0 +1,113 @@ +import { + AndroidConfig, + withPlugins, + type ExportedConfig, + type ExportedConfigWithProps, +} from 'expo/config-plugins' +import withReactNativePay from '../index' +import type { ReactNativePayPluginProps } from '../type' + +const GOOGLE_PAY_META_NAME = 'com.google.android.gms.wallet.api.enabled' + +function createManifest( + existingValue?: string +): AndroidConfig.Manifest.AndroidManifest { + return { + manifest: { + $: { 'xmlns:android': 'http://schemas.android.com/apk/res/android' }, + queries: [], + application: [ + { + '$': { 'android:name': '.MainApplication' }, + 'meta-data': existingValue + ? [ + { + $: { + 'android:name': GOOGLE_PAY_META_NAME, + 'android:value': existingValue, + }, + }, + ] + : [], + }, + ], + }, + } +} + +// Same entry shapes Expo resolves from app.json: a bare name or [name, props] +function applyPlugin(props?: ReactNativePayPluginProps): ExportedConfig { + const config = { + name: 'app', + slug: 'app', + _internal: { projectRoot: __dirname }, + } + return withPlugins(config, [ + props === undefined ? withReactNativePay : [withReactNativePay, props], + ]) +} + +async function runManifestMods( + config: ExportedConfig, + manifest: AndroidConfig.Manifest.AndroidManifest +): Promise { + const mod = config.mods?.android?.manifest + if (!mod) { + return manifest + } + const result = await mod({ + ...config, + modResults: manifest, + } as ExportedConfigWithProps) + return result.modResults +} + +function googlePayValue(manifest: AndroidConfig.Manifest.AndroidManifest) { + return AndroidConfig.Manifest.getMainApplicationMetaDataValue( + manifest, + GOOGLE_PAY_META_NAME + ) +} + +describe('withReactNativePay with Expo mods', () => { + it('runs when listed without options and changes nothing', async () => { + const config = applyPlugin() + + expect(config.mods?.android?.manifest).toBeUndefined() + expect(config.mods?.ios?.entitlements).toBeUndefined() + expect(config.mods?.ios?.infoPlist).toBeUndefined() + }) + + it('keeps an existing Google Pay entry when enableGooglePay is omitted', async () => { + const config = applyPlugin({ merchantIdentifier: 'merchant.com.test' }) + + const manifest = await runManifestMods(config, createManifest('true')) + + expect(googlePayValue(manifest)).toBe('true') + }) + + it('adds the Google Pay entry once when enableGooglePay is true', async () => { + const config = applyPlugin({ enableGooglePay: true }) + + expect( + googlePayValue(await runManifestMods(config, createManifest())) + ).toBe('true') + + const manifest = await runManifestMods(config, createManifest('true')) + const metaData = + AndroidConfig.Manifest.getMainApplicationOrThrow(manifest)['meta-data'] + expect( + metaData?.filter( + (item) => item.$['android:name'] === GOOGLE_PAY_META_NAME + ) + ).toHaveLength(1) + }) + + it('removes the Google Pay entry when enableGooglePay is false', async () => { + const config = applyPlugin({ enableGooglePay: false }) + + const manifest = await runManifestMods(config, createManifest('true')) + + expect(googlePayValue(manifest)).toBeNull() + }) +}) diff --git a/package/src/plugin/__tests__/index.test.ts b/package/src/plugin/__tests__/index.test.ts index dacf5be..d2bcbb0 100644 --- a/package/src/plugin/__tests__/index.test.ts +++ b/package/src/plugin/__tests__/index.test.ts @@ -34,4 +34,16 @@ describe('withReactNativePay', () => { ) expect(result).toEqual({ name: 'my-app', googlePay: true, applePay: true }) }) + + it('passes empty props when listed without options', () => { + const inputConfig = { name: 'my-app' } + + withReactNativePay(inputConfig as any, undefined) + + expect(mockWithGooglePay).toHaveBeenCalledWith(inputConfig, {}) + expect(mockWithApplePay).toHaveBeenCalledWith( + { name: 'my-app', googlePay: true }, + {} + ) + }) }) diff --git a/package/src/plugin/__tests__/withApplePay.test.ts b/package/src/plugin/__tests__/withApplePay.test.ts index f42ec38..766031f 100644 --- a/package/src/plugin/__tests__/withApplePay.test.ts +++ b/package/src/plugin/__tests__/withApplePay.test.ts @@ -13,7 +13,12 @@ const mockWithInfoPlist = jest.fn( action('modResults' in config ? config : { modResults: config }) ) +const mockAddWarningIOS = jest.fn() + jest.mock('expo/config-plugins', () => ({ + WarningAggregator: { + addWarningIOS: (...args: any[]) => mockAddWarningIOS(...args), + }, withEntitlementsPlist: (config: any, action: (input: any) => any) => mockWithEntitlementsPlist(config, action), withInfoPlist: (config: any, action: (input: any) => any) => @@ -57,9 +62,13 @@ describe('withApplePay', () => { }) }) - it('does not modify config when merchantIdentifier is missing', () => { + it.each([ + ['is missing', {}], + ['is an empty list', { merchantIdentifier: [] }], + ['has only empty IDs', { merchantIdentifier: [''] }], + ])('does not modify config when merchantIdentifier %s', (_label, props) => { const config = { name: 'app' } - const result = withApplePay(config as any, {}) + const result = withApplePay(config as any, props) expect(result).toBe(config) expect(mockWithEntitlementsPlist).not.toHaveBeenCalled() expect(mockWithInfoPlist).not.toHaveBeenCalled() @@ -80,4 +89,34 @@ describe('withApplePay', () => { }, }) }) + + it('warns about merchant identifiers without the merchant. prefix and still adds them', () => { + const result = withApplePay({} as any, { + merchantIdentifier: ['merchant.com.ok', 'com.example.app', ''], + }) + + expect(mockAddWarningIOS).toHaveBeenCalledTimes(1) + expect(mockAddWarningIOS).toHaveBeenCalledWith( + '@gmisoftware/react-native-pay', + expect.stringContaining('"com.example.app"'), + expect.any(String) + ) + expect(result).toEqual({ + modResults: { + 'com.apple.developer.in-app-payments': [ + 'merchant.com.ok', + 'com.example.app', + ], + 'ReactNativePayApplePayMerchantIdentifiers': [ + 'merchant.com.ok', + 'com.example.app', + ], + }, + }) + }) + + it('does not warn about valid merchant identifiers', () => { + withApplePay({} as any, { merchantIdentifier: 'merchant.com.test' }) + expect(mockAddWarningIOS).not.toHaveBeenCalled() + }) }) diff --git a/package/src/plugin/__tests__/withGooglePay.test.ts b/package/src/plugin/__tests__/withGooglePay.test.ts index c407f7f..a0e9053 100644 --- a/package/src/plugin/__tests__/withGooglePay.test.ts +++ b/package/src/plugin/__tests__/withGooglePay.test.ts @@ -63,4 +63,17 @@ describe('withGooglePay', () => { expect(result).toEqual({ modResults: { name: 'app' } }) expect(mockAddMetaDataItemToMainApplication).toHaveBeenCalled() }) + + it.each([ + ['enableGooglePay is omitted', {}], + ['enableGooglePay is null', { enableGooglePay: null } as any], + ])('leaves the manifest alone when %s', (_label, props) => { + const config = { name: 'app' } + const result = withGooglePay(config as any, props) + + expect(result).toBe(config) + expect(mockWithAndroidManifest).not.toHaveBeenCalled() + expect(mockAddMetaDataItemToMainApplication).not.toHaveBeenCalled() + expect(mockRemoveMetaDataItemFromMainApplication).not.toHaveBeenCalled() + }) }) diff --git a/package/src/plugin/index.ts b/package/src/plugin/index.ts index ff7b7c9..45800fc 100644 --- a/package/src/plugin/index.ts +++ b/package/src/plugin/index.ts @@ -3,13 +3,15 @@ import type { ReactNativePayPluginProps } from './type' import { withApplePay } from './withApplePay' import { withGooglePay } from './withGooglePay' -const withReactNativePay: ConfigPlugin = ( +const withReactNativePay: ConfigPlugin = ( config, props ) => { - config = withGooglePay(config, props) + const options = props ?? {} - config = withApplePay(config, props) + config = withGooglePay(config, options) + + config = withApplePay(config, options) return config } diff --git a/package/src/plugin/type.ts b/package/src/plugin/type.ts index 8738529..7ba7c4b 100644 --- a/package/src/plugin/type.ts +++ b/package/src/plugin/type.ts @@ -1,4 +1,13 @@ export interface ReactNativePayPluginProps { + /** + * Apple Pay merchant ID(s), each starting with `merchant.`. If omitted, the + * Apple Pay entitlement is not added. + */ merchantIdentifier?: string | string[] + /** + * `true` adds the Google Pay meta-data to the Android manifest and `false` + * removes it. If omitted, the manifest is left as it is, so an entry added + * by another plugin stays. + */ enableGooglePay?: boolean } diff --git a/package/src/plugin/withApplePay.ts b/package/src/plugin/withApplePay.ts index ccdce11..c4f1c02 100644 --- a/package/src/plugin/withApplePay.ts +++ b/package/src/plugin/withApplePay.ts @@ -1,4 +1,5 @@ import { + WarningAggregator, withEntitlementsPlist, withInfoPlist, type ConfigPlugin, @@ -7,6 +8,7 @@ import type { ReactNativePayPluginProps } from './type' const APPLE_PAY_ENTITLEMENT_KEY = 'com.apple.developer.in-app-payments' const APPLE_PAY_INFO_PLIST_KEY = 'ReactNativePayApplePayMerchantIdentifiers' +const MERCHANT_ID_PREFIX = 'merchant.' export function setApplePayEntitlement( merchantIdentifiers: string | string[], @@ -49,22 +51,31 @@ export const withApplePay: ConfigPlugin = ( expoConfig, { merchantIdentifier } ) => { + const merchantIds = [merchantIdentifier ?? []].flat().filter(Boolean) + // If merchantIdentifier is not passed Apple Pay won't be initialize - if (!merchantIdentifier) { + if (!merchantIds.length) { return expoConfig } + for (const id of merchantIds) { + if (!id.startsWith(MERCHANT_ID_PREFIX)) { + WarningAggregator.addWarningIOS( + '@gmisoftware/react-native-pay', + `merchantIdentifier "${id}" does not start with "${MERCHANT_ID_PREFIX}". Apple Pay merchant IDs look like "merchant.com.example.app".`, + 'https://gmi-software.github.io/react-native-pay/docs/setup/ios-apple-pay' + ) + } + } + const withEntitlements = withEntitlementsPlist(expoConfig, (config) => { - config.modResults = setApplePayEntitlement( - merchantIdentifier, - config.modResults - ) + config.modResults = setApplePayEntitlement(merchantIds, config.modResults) return config }) return withInfoPlist(withEntitlements, (config) => { config.modResults = setApplePayMerchantIdentifiersInInfoPlist( - merchantIdentifier, + merchantIds, config.modResults ) return config diff --git a/package/src/plugin/withGooglePay.ts b/package/src/plugin/withGooglePay.ts index efcc663..7ea9695 100644 --- a/package/src/plugin/withGooglePay.ts +++ b/package/src/plugin/withGooglePay.ts @@ -13,8 +13,12 @@ const { export const withGooglePay: ConfigPlugin = ( expoConfig, - { enableGooglePay = false } + { enableGooglePay } ) => { + if (enableGooglePay == null) { + return expoConfig + } + return withAndroidManifest(expoConfig, (config) => { config.modResults = setGooglePayMetaData(enableGooglePay, config.modResults) return config