Document why appVersion stays explicit, and prove an unreadable one fails open

Author: meliharik

CHANGELOG.md

@@ -2,6 +2,10 @@
 
 ## Unreleased
 
+- `appVersion` stays required here, while the Swift and Flutter SDKs now detect
+  it. React Native exposes nothing that reads the host app's version — reaching
+  the bundle needs a native module, and this package having none is worth more
+  than saving a caller one argument. Documented rather than papered over.
 - Removed the kill switch, following its removal from the protocol. Evaluation
   order is now maintenance → force → soft → none. Old payloads that still carry
   a `kill` block parse fine; the block is ignored.

README.md

@@ -25,9 +25,9 @@ No native modules, no pod install, no config plugin. It is JavaScript.
 ## Quick start
 
 ```tsx
-import { RipstopProvider } from '@ripstop/react-native';
 import AsyncStorage from '@react-native-async-storage/async-storage';
-import { asyncStorageAdapter } from '@ripstop/react-native';
+import DeviceInfo from 'react-native-device-info';
+import { RipstopProvider, asyncStorageAdapter } from '@ripstop/react-native';
 
 export default function App() {
   return (
@@ -45,6 +45,26 @@ export default function App() {
 That's the whole integration. The provider renders your app until a decision
 says otherwise, then shows the right wall.
 
+## Why you still pass `appVersion`
+
+The other Ripstop SDKs read the installed version themselves — Swift from
+`CFBundleShortVersionString`, Flutter from `package_info_plus`. React Native
+cannot. Nothing in the framework exposes the host app's version: `Platform.OS`
+and `Platform.Version` describe the operating system, and
+`Platform.constants.reactNativeVersion` describes React Native. Reading the
+bundle means a native module, and this package has none — see the installation
+note above, which is a promise worth more than saving you one argument.
+
+So pass it, from whichever of these you already have:
+
+```tsx
+import DeviceInfo from 'react-native-device-info';   // DeviceInfo.getVersion()
+import Constants from 'expo-constants';              // Constants.expoConfig?.version
+```
+
+Pass the version only — `1.4.0`, not `1.4.0 (312)`. Build numbers are not part
+of a semantic version, and the rules are compared as semantic versions.
+
 ## Or draw your own
 
 ```tsx

src/client.ts

@@ -18,7 +18,18 @@ const DEFAULT_ENDPOINT = 'https://cfg.ripstop.dev/v1/config';
 
 export interface RipstopOptions {
   apiKey: string;
-  /** The build the page is running. Rules are evaluated against this. */
+  /**
+   * The build this app is running. Rules are evaluated against it.
+   *
+   * Required, unlike the Swift and Flutter SDKs, which read it themselves.
+   * React Native exposes no way to: `Platform.Version` is the OS and
+   * `Platform.constants.reactNativeVersion` is the framework, and reaching the
+   * bundle means a native module. This package has none, and that is worth
+   * more than saving a caller one argument.
+   *
+   * The version only — `1.4.0`, not `1.4.0 (312)`. Build numbers are not part
+   * of a semantic version, and these are compared as semantic versions.
+   */
   appVersion: string;
   platform?: Platform;
   locale?: string;

test/client.test.ts

@@ -120,6 +120,18 @@ describe('the client', () => {
     expect(gate.source).toBe('none');
   });
 
+  it('has no opinion about a version it cannot read', async () => {
+    // `appVersion` is required here because React Native will not tell us the
+    // installed version, which puts the value in the caller's hands — so the
+    // common mistakes have to fail open rather than wall somebody. A display
+    // string with the build number in it is the one people reach for.
+    const { impl } = server(config());
+    for (const appVersion of ['', '1.4.0 (312)', 'v3.0.0']) {
+      const gate = await boot(impl, { appVersion });
+      expect((await gate.check()).type, appVersion).toBe('none');
+    }
+  });
+
   it('refuses an unknown key id', async () => {
     const { impl } = server(config());
     const gate = await boot(impl, { signingKeys: { other: publicKeyB64 } });