@testerpaykit/expo 2.1.2 → 2.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/CHANGELOG.md CHANGED
@@ -2,6 +2,86 @@
2
2
 
3
3
  All notable changes to `@testerpaykit/expo` are documented here.
4
4
 
5
+ ## 2.2.0 — 2026-11-15
6
+
7
+ ### Changed (voice first)
8
+ - `TesterPayKitWrapper`: "Report Bug" and shake open the voice sheet; the
9
+ spoken draft lands on review. New `reportMode` prop (`'voice'` default,
10
+ `'form'` for the form first).
11
+ - `FloatingFeedbackButton`: new `onDetailedReport` adds "Report in detail"
12
+ (the form) above "End session".
13
+ - `VoiceBugInputSheet`: new `onTypeInstead` shows "Type instead" before
14
+ recording and after a failed one; the wrapper opens the form on the
15
+ details step.
16
+
17
+ ### Breaking
18
+ - **SMS confirmation removed.** A tested app no longer asks for a phone number
19
+ or an SMS code. `startPhone()` and `confirmPhone()` are gone, and so are the
20
+ number and code steps of `PhoneConfirmSheet`. Its `tpk` prop now needs
21
+ `linkWithTpkApp` and `checkAppLink`, and `onDone` gets only
22
+ `awaitingApproval`.
23
+ - **Release builds are inert unless built with channel `beta`.** TesterPayKit
24
+ now runs only in beta builds (TestFlight, Google Play test tracks); App Store
25
+ Guideline 2.2 forbids beta-testing features in a store build, and App Review
26
+ runs in the StoreKit sandbox too, so no runtime signal can tell them apart.
27
+ The channel is fixed at build time by the config plugin (`channel` prop, else
28
+ the `TPK_CHANNEL` environment variable of the build). Without one, `__DEV__`
29
+ builds count as `beta` and release builds as `store`. In a `store` build
30
+ `TpkExpo.init()` resolves to `null` (its return type is now
31
+ `Promise<TpkExpo | null>`) without any network call or storage write,
32
+ `TesterPayKitProvider` renders its children with `client: null`, and
33
+ `TesterPayKitWrapper` renders its children unchanged.
34
+ - **The config plugin adds the microphone only to beta builds.** With channel
35
+ `store` or none, `NSMicrophoneUsageDescription` and `RECORD_AUDIO` are no
36
+ longer added. Any other channel value fails the build. The plugin now needs
37
+ `expo` and `expo-constants` (both ship with every Expo app; new peer
38
+ dependencies).
39
+
40
+ ### Added
41
+ - **`<TpkVersionCheck projectId=… />`: update hint with a link to the store
42
+ and "what's new"** once per installed version, from the store releases
43
+ kept in TesterPayKit. Runs in beta and store builds without
44
+ `TpkExpo.init()`; one anonymous request
45
+ (`GET /public/apps/{projectId}/release`), no personal data, silent on any
46
+ error or after 5 s. A required update cannot be dismissed; "Später" /
47
+ "Later" waits for the next store version; "what's new" never shows on a
48
+ fresh install. Also exported: `fetchVersionNotice`, `decideVersionNotice`,
49
+ `dismissVersionUpdate`, `TpkWhatsNewSheet` and the `TpkVersionNotice`
50
+ type.
51
+ - **`getBuildChannel()` and `TpkExpo.channel`** return the build channel
52
+ (`'beta' | 'store'`, type `TpkBuildChannel`), so apps can hide their own
53
+ TesterPayKit entries in store builds. The plugin writes it to
54
+ `extra.testerpaykit.channel`.
55
+ - **Google Play refuses beta builds in production.** A beta build's Android
56
+ manifest gets the meta-data
57
+ `com.google.android.play.largest_release_audience` = `NONPRODUCTION`.
58
+ - **Confirm once with the TPK app.** The sheet behind `openVerification()`
59
+ says "Einmal mit der TPK-App bestätigen" / "Confirm once with the TPK app".
60
+ Its button creates a link (`tpk.linkWithTpkApp()`, POST
61
+ `/v1/testers/me/phone/link` with project and platform) and opens the TPK app,
62
+ or the web page when the app is missing ("Noch keine TPK-App?" opens the web
63
+ page directly). The sheet then asks the server every 2 s and whenever the
64
+ app comes back to the front (`tpk.checkAppLink()`), for at most 15 minutes.
65
+ Confirmed: it closes, the widget appears and queued reports go out. Not
66
+ approved yet: the waiting-for-approval note. Closing the sheet stops asking.
67
+ - **Version check.** Every request to the TesterPayKit API (also uploads,
68
+ polling, the live link and AI-run sockets, and the version notice) carries
69
+ `X-TPK-Client: expo/<version>` (`TPK_CLIENT_ID`). When the server answers
70
+ 426 `client_outdated` (this SDK is below its minimum), the SDK sends
71
+ nothing more for this app run: requests are refused locally without
72
+ throwing into the app, periodic flushes stop, and queued reports stay
73
+ queued for the new build. `TesterPayKitWrapper` tells the tester once:
74
+ "TesterPayKit in dieser App ist zu alt (Version {yours}, nötig {min}).
75
+ Bitte installiere die neue Testversion." / "TesterPayKit in this app is
76
+ too old ({yours}, needs {min}). Please install the new test build."
77
+ Read the state with `getClientOutdated()`, `onClientOutdated(listener)` or
78
+ the hook `useTpkClientOutdated()`. The public version notice keeps working.
79
+
80
+ ## 2.1.3 — 2026-11-09
81
+
82
+ - No change of its own. Follows the release train, which moved for a fix in the
83
+ Flutter and Swift SDKs.
84
+
5
85
  ## 2.1.2 — 2026-11-09
6
86
 
7
87
  ### Fixed
package/README.md CHANGED
@@ -9,11 +9,13 @@ package-owned bug-report UI shell.
9
9
  ```bash
10
10
  npx expo install \
11
11
  @testerpaykit/expo \
12
- @react-native-async-storage/async-storage \
12
+ @react-native-async-storage/async-storage expo-constants \
13
13
  expo-sensors expo-device expo-application expo-file-system expo-audio
14
14
  ```
15
15
 
16
- Native modules are peer-optional. Without them the related feature
16
+ `expo-constants` is required: it carries the build channel (see
17
+ [Beta and store builds](#beta-and-store-builds)). The other native modules
18
+ are peer-optional. Without them the related feature
17
19
  no-ops or falls back — and since 0.6.x a **dev-mode setup check** logs
18
20
  one line per missing module at init so gaps surface at integration
19
21
  time, not in the moment a tester hits the feature:
@@ -35,14 +37,65 @@ with a built-in fallback chain (`crypto.randomUUID` → `crypto.
35
37
  getRandomValues` → `expo-crypto` → seeded `Math.random`), so
36
38
  `react-native-get-random-values` is optional, not a hidden must.
37
39
 
38
- ### Microphone permission (voice bug reports)
40
+ ### Beta and store builds
41
+
42
+ TesterPayKit belongs in **beta builds only** (TestFlight, Google Play test
43
+ tracks). Apple rejects App Store builds with beta-testing features
44
+ (Guideline 2.2), and App Review runs in the StoreKit sandbox too, so the SDK
45
+ cannot tell a reviewer from a tester at runtime, and a server switch would be
46
+ a hidden feature (2.5.19). Build the app twice from the same code instead;
47
+ the channel is fixed at build time by the config plugin:
48
+
49
+ ```js
50
+ // app.config.js
51
+ export default {
52
+ expo: {
53
+ plugins: [['@testerpaykit/expo', { channel: process.env.TPK_CHANNEL }]],
54
+ },
55
+ };
56
+ ```
57
+
58
+ ```json
59
+ // eas.json: the beta profile sets the channel, production leaves it out
60
+ {
61
+ "build": {
62
+ "beta": { "env": { "TPK_CHANNEL": "beta" } },
63
+ "production": { "env": { "TPK_CHANNEL": "store" } }
64
+ }
65
+ }
66
+ ```
67
+
68
+ Without the `channel` prop the plugin reads `TPK_CHANNEL` itself, so
69
+ `"plugins": ["@testerpaykit/expo"]` plus the EAS env works as well.
70
+
71
+ | Channel | When | TesterPayKit |
72
+ |---|---|---|
73
+ | `beta` | set explicitly, or nothing set in a `__DEV__` build | active; microphone permission and the Play `NONPRODUCTION` meta-data are added |
74
+ | `store` | set explicitly, or nothing set in a release build | completely inert: `TpkExpo.init()` resolves to `null` without any network call or storage write, `TesterPayKitProvider` and `TesterPayKitWrapper` render their children unchanged; no microphone permission, no meta-data |
75
+
76
+ A beta build's Android manifest gets
77
+ `<meta-data android:name="com.google.android.play.largest_release_audience" android:value="NONPRODUCTION"/>`,
78
+ so Google Play itself refuses to release it to production
79
+ ([release audience restriction](https://developer.android.com/google/play/release-audience-restriction)).
80
+
81
+ The plugin writes the channel to `extra.testerpaykit.channel`; read it with
82
+ `getBuildChannel()` (or `TpkExpo.channel`) to hide your own TesterPayKit
83
+ entries, e.g. a "Become a tester" row, in store builds:
84
+
85
+ ```tsx
86
+ import { getBuildChannel } from '@testerpaykit/expo';
87
+
88
+ {getBuildChannel() === 'beta' && <BecomeTesterRow />}
89
+ ```
90
+
91
+ ### Microphone permission (voice bug reports, beta builds)
39
92
 
40
93
  Voice bug reports record audio. iOS **crashes** the first time the app
41
94
  touches the microphone if `NSMicrophoneUsageDescription` is missing from
42
95
  Info.plist — and that crash happens in the native layer, so the SDK's
43
- error handling cannot catch it. Add this package's config plugin to
44
- inject the iOS usage description **and** the Android `RECORD_AUDIO`
45
- permission:
96
+ error handling cannot catch it. In a beta build this package's config
97
+ plugin injects the iOS usage description **and** the Android
98
+ `RECORD_AUDIO` permission; a store build gets neither:
46
99
 
47
100
  ```json
48
101
  // app.json
@@ -50,6 +103,7 @@ permission:
50
103
  "expo": {
51
104
  "plugins": [
52
105
  ["@testerpaykit/expo", {
106
+ "channel": "beta",
53
107
  "microphonePermission": "Allow $(PRODUCT_NAME) to record voice bug reports."
54
108
  }]
55
109
  ]
@@ -74,6 +128,7 @@ export function App() {
74
128
 
75
129
  useEffect(() => {
76
130
  (async () => {
131
+ // null in a store build: the app runs without TesterPayKit.
77
132
  const client = await TpkExpo.init({
78
133
  projectId: '8980ca35-8697-4d8c-ae3f-0677c7d177d1',
79
134
  testerCode: 'demo-tester-01',
@@ -172,7 +227,8 @@ into `TesterPayKitProvider` instead of `config`.
172
227
 
173
228
  `<TesterPayKitWrapper>` shows its button, shake-to-report, the voice flow
174
229
  and every tester sheet **only** for a tester with a confirmed phone number
175
- **and** an admin's approval — in every build, TestFlight included.
230
+ **and** an admin's approval — in every build, TestFlight included. The
231
+ number is confirmed once in the TesterPayKit app, never by SMS in your app.
176
232
  Everyone else sees your app and nothing from TesterPayKit.
177
233
 
178
234
  ```ts
@@ -183,8 +239,11 @@ await tpk.refreshAccess(); // re-asks the server (offline keeps the cache)
183
239
  await tpk.openVerification(); // your own "Become a tester" entry
184
240
  ```
185
241
 
186
- `openVerification()` opens the wrapper's phone sheet when the number is
187
- not confirmed yet and says so when the approval is pending. Access is
242
+ `openVerification()` opens the wrapper's sheet "Confirm once with the TPK
243
+ app" when the number is not confirmed yet: it opens the TPK app
244
+ (`testerpaykit://link/…`, else the web page with an install hint), waits for
245
+ the person to allow it there and then closes on its own. It says so when the
246
+ approval is pending. Access is
188
247
  re-checked whenever the app comes to the front; any 403
189
248
  `phone_required` / `approval_required` hides the widget at once. If you
190
249
  render `<TpkOnboarding>` or `<TpkWelcomeSheet>` yourself, render them only
@@ -203,6 +262,8 @@ names the tester.
203
262
 
204
263
  ## What `TpkExpo.init()` does
205
264
 
265
+ 0. In a `store` build: nothing. It resolves to `null` (see
266
+ [Beta and store builds](#beta-and-store-builds)).
206
267
  1. Reads cached anonymous-tester JWT from AsyncStorage (key
207
268
  `@testerpaykit/auth`). If the cached entry matches the current
208
269
  `projectId` + `testerCode`, reuse it — skip the network round
@@ -372,6 +433,90 @@ pin one language for all testers:
372
433
  Standalone sheets outside the wrapper take the same setting from
373
434
  `<TpkLanguageProvider language="de">`.
374
435
 
436
+ ## Update hint and "what's new"
437
+
438
+ `<TpkVersionCheck>` works in **both** channels, also in store builds where
439
+ `TpkExpo.init()` returns `null` and the rest of TesterPayKit is off. It
440
+ needs no `init`. It sends one anonymous request with the project id,
441
+ platform, installed version and language (no token, no device data,
442
+ nothing stored) and shows at most one thing:
443
+
444
+ - a **required update**: a dialog that only leads to the store;
445
+ - an **available update**: once per new store version, with "Later";
446
+ - otherwise **"what's new"** for the installed version, once, but not on
447
+ the first start of a fresh install.
448
+
449
+ ```tsx
450
+ import { TpkVersionCheck } from '@testerpaykit/expo';
451
+
452
+ export default function RootLayout() {
453
+ return (
454
+ <>
455
+ <Stack />
456
+ <TpkVersionCheck projectId="<project-uuid>" />
457
+ </>
458
+ );
459
+ }
460
+ ```
461
+
462
+ It checks once on mount. The installed version comes from
463
+ `expo-application` (`nativeApplicationVersion`), else from the app config
464
+ (`expo-constants`); the language from `TpkLanguageProvider` or the device.
465
+ The seen and dismissed versions live in AsyncStorage
466
+ (`tpk_version_notice_seen`, `tpk_version_notice_dismissed`); pass
467
+ `storage` to use your own `TpkStorage`.
468
+
469
+ The app never updates itself; the button opens the App Store, Google Play
470
+ or web page set for the release (`Linking.openURL`). Store releases
471
+ (version, notes in German and English, store link, required) are kept per
472
+ platform in the console, with `tpk release add` or the API. iOS, Android
473
+ and web are supported; other platforms get no notice. Any network or
474
+ parse error, or no answer within 5 seconds, shows nothing.
475
+ `fetchVersionNotice({ projectId })` returns the raw `TpkVersionNotice` if
476
+ you want to render it yourself (with `decideVersionNotice` and
477
+ `dismissVersionUpdate` for the once-per-version rules), and
478
+ `<TpkWhatsNewSheet notice={…} visible onClose={…} />` shows "what's new"
479
+ on demand, e.g. from a settings row.
480
+
481
+ Store review: mention the update hint and "what's new" in the review
482
+ notes. List no collected data for it in the App Privacy section or Google
483
+ Play's Data safety form: the request carries no personal data and is not
484
+ stored.
485
+
486
+ ## Version check
487
+
488
+ Every request to the TesterPayKit API carries `X-TPK-Client: expo/<version>`
489
+ (exported as `TPK_CLIENT_ID`): the REST calls, uploads, polling, the live
490
+ link and AI-run sockets, and the version notice. The server keeps a minimum
491
+ version per client kind. Below it, it answers **426** `client_outdated`
492
+ with `{ kind, min, yours, message }`.
493
+
494
+ From the first 426 on, this app run is **outdated**:
495
+
496
+ - the SDK sends nothing more: requests are refused before they reach the
497
+ network, without throwing into your app; periodic flushes stop;
498
+ - reports submitted now, and those already queued, stay in the queue for
499
+ the new build (`submitBug` returns `outcome: 'queued'`);
500
+ - `TesterPayKitWrapper` shows the tester a notice once, until tapped away:
501
+ "TesterPayKit in dieser App ist zu alt (Version 2.2.0, nötig 2.3.0).
502
+ Bitte installiere die neue Testversion." / "TesterPayKit in this app is
503
+ too old (2.2.0, needs 2.3.0). Please install the new test build."
504
+
505
+ Store builds never see this: there TesterPayKit sends nothing at all. The
506
+ public version notice (`<TpkVersionCheck>`, `/public/**`) is never refused
507
+ and keeps working in an outdated app.
508
+
509
+ ```tsx
510
+ import {
511
+ getClientOutdated,
512
+ onClientOutdated,
513
+ useTpkClientOutdated,
514
+ } from '@testerpaykit/expo';
515
+
516
+ const outdated = useTpkClientOutdated(); // null, or { kind, min, yours, message }
517
+ const off = onClientOutdated((info) => log(info.min));
518
+ ```
519
+
375
520
  ## AI test runs started from outside
376
521
 
377
522
  The wrapper can hand the app to an AI tester that a coordinator starts
package/app.plugin.js CHANGED
@@ -1,5 +1,30 @@
1
1
  // Expo config plugin for @testerpaykit/expo.
2
2
  //
3
+ // ── Build channel: beta or store ──
4
+ //
5
+ // Apple rejects App Store builds that carry beta-testing features
6
+ // (Guideline 2.2), and App Review runs in the StoreKit sandbox too, so the
7
+ // app cannot tell a reviewer from a tester at runtime. The app is built
8
+ // twice from the same code instead:
9
+ //
10
+ // • beta — TestFlight / Google Play test tracks. TesterPayKit is active.
11
+ // • store — App Store / Play production. TesterPayKit is completely inert.
12
+ //
13
+ // The channel comes from the plugin prop `channel`, else from the
14
+ // TPK_CHANNEL environment variable of the build (e.g. per EAS build
15
+ // profile). It is written to `extra.testerpaykit.channel`, where the SDK
16
+ // reads it via expo-constants (`getBuildChannel()`). Unset: development
17
+ // builds (`__DEV__`) count as beta, release builds as store.
18
+ //
19
+ // // app.config.js
20
+ // plugins: [['@testerpaykit/expo', { channel: process.env.TPK_CHANNEL }]]
21
+ // // eas.json → build.beta.env: { "TPK_CHANNEL": "beta" }
22
+ //
23
+ // Only a beta build gets the native parts below; a store build carries no
24
+ // microphone permission and no TesterPayKit trace in its manifests.
25
+ //
26
+ // ── Beta only: microphone ──
27
+ //
3
28
  // The voice-bug feature (VoiceBugInputSheet) records audio through
4
29
  // expo-audio. Two native facts the JS layer cannot paper over:
5
30
  //
@@ -11,18 +36,16 @@
11
36
  // • Android — without the RECORD_AUDIO permission the request
12
37
  // returns { granted: false } and voice quietly disables.
13
38
  //
14
- // This plugin injects both so integrators get a working microphone by
15
- // adding one line:
16
- //
17
- // // app.json
18
- // "plugins": ["@testerpaykit/expo"]
39
+ // Custom iOS prompt: { channel: 'beta', microphonePermission: '…' }.
40
+ // microphonePermission: false opts out of the microphone entirely.
19
41
  //
20
- // // …or with a custom iOS prompt:
21
- // "plugins": [["@testerpaykit/expo", { "microphonePermission": "…" }]]
42
+ // ── Beta only: Google Play release audience ──
22
43
  //
23
- // Pass microphonePermission: false to opt out entirely (e.g. you don't
24
- // use voice bug reports and don't want the permission on your store
25
- // listing).
44
+ // The Android manifest gets
45
+ // <meta-data android:name="com.google.android.play.largest_release_audience"
46
+ // android:value="NONPRODUCTION"/>
47
+ // so Google Play itself refuses to roll a beta build out to production
48
+ // (https://developer.android.com/google/play/release-audience-restriction).
26
49
  //
27
50
  // ⚠️ Config-plugin changes only take effect after a FRESH NATIVE BUILD
28
51
  // (`npx expo prebuild --clean`, a new dev-client, or an EAS build) —
@@ -31,19 +54,46 @@
31
54
  const DEFAULT_MIC_MESSAGE =
32
55
  'Allow $(PRODUCT_NAME) to record voice bug reports.';
33
56
 
57
+ const RELEASE_AUDIENCE_KEY = 'com.google.android.play.largest_release_audience';
58
+ const RELEASE_AUDIENCE_VALUE = 'NONPRODUCTION';
59
+
34
60
  /**
35
- * @param {object} config the Expo app config
36
- * @param {{ microphonePermission?: string | false }} [props]
61
+ * `beta`, `store` or undefined. Anything else fails the build: a typo must
62
+ * not silently ship a store build with beta features or the other way round.
63
+ *
64
+ * @param {unknown} value
65
+ * @returns {'beta' | 'store' | undefined}
37
66
  */
38
- module.exports = function withTesterPayKit(config, props = {}) {
39
- const micMessage =
40
- props.microphonePermission === undefined
41
- ? DEFAULT_MIC_MESSAGE
42
- : props.microphonePermission;
67
+ function resolveChannel(value) {
68
+ if (value === undefined || value === null) return undefined;
69
+ const channel = String(value).trim().toLowerCase();
70
+ if (channel === '') return undefined;
71
+ if (channel === 'beta' || channel === 'store') return channel;
72
+ throw new Error(
73
+ `@testerpaykit/expo: channel must be "beta" or "store", got "${value}".`,
74
+ );
75
+ }
43
76
 
44
- // Explicit opt-out — touch nothing.
45
- if (micMessage === false) return config;
77
+ /**
78
+ * Adds the release-audience meta-data to <application> of a
79
+ * AndroidManifest object (the shape withAndroidManifest hands over).
80
+ */
81
+ function addReleaseAudience(manifest) {
82
+ const app = manifest.manifest.application?.[0];
83
+ if (!app) return manifest;
84
+ app['meta-data'] = (app['meta-data'] || []).filter(
85
+ (item) => item.$['android:name'] !== RELEASE_AUDIENCE_KEY,
86
+ );
87
+ app['meta-data'].push({
88
+ $: {
89
+ 'android:name': RELEASE_AUDIENCE_KEY,
90
+ 'android:value': RELEASE_AUDIENCE_VALUE,
91
+ },
92
+ });
93
+ return manifest;
94
+ }
46
95
 
96
+ function withMicrophone(config, micMessage) {
47
97
  // iOS — required, or the app crashes on first mic access.
48
98
  config.ios = config.ios || {};
49
99
  config.ios.infoPlist = config.ios.infoPlist || {};
@@ -60,6 +110,44 @@ module.exports = function withTesterPayKit(config, props = {}) {
60
110
  ) {
61
111
  config.android.permissions.push('android.permission.RECORD_AUDIO');
62
112
  }
63
-
64
113
  return config;
65
- };
114
+ }
115
+
116
+ /**
117
+ * @param {object} config the Expo app config
118
+ * @param {{ channel?: 'beta' | 'store', microphonePermission?: string | false }} [props]
119
+ */
120
+ function withTesterPayKit(config, props = {}) {
121
+ const channel = resolveChannel(
122
+ props.channel !== undefined ? props.channel : process.env.TPK_CHANNEL,
123
+ );
124
+
125
+ config.extra = config.extra || {};
126
+ config.extra.testerpaykit = { ...config.extra.testerpaykit };
127
+ if (channel) {
128
+ config.extra.testerpaykit.channel = channel;
129
+ } else {
130
+ // A stale value from an earlier config must not decide the channel.
131
+ delete config.extra.testerpaykit.channel;
132
+ }
133
+
134
+ if (channel !== 'beta') return config;
135
+
136
+ const micMessage =
137
+ props.microphonePermission === undefined
138
+ ? DEFAULT_MIC_MESSAGE
139
+ : props.microphonePermission;
140
+ if (micMessage !== false) withMicrophone(config, micMessage);
141
+
142
+ // expo/config-plugins ships with every Expo app (via the `expo` package);
143
+ // loaded here so the store path never needs it.
144
+ const { withAndroidManifest } = require('expo/config-plugins');
145
+ return withAndroidManifest(config, (mod) => {
146
+ mod.modResults = addReleaseAudience(mod.modResults);
147
+ return mod;
148
+ });
149
+ }
150
+
151
+ module.exports = withTesterPayKit;
152
+ module.exports.resolveChannel = resolveChannel;
153
+ module.exports.addReleaseAudience = addReleaseAudience;