@testerpaykit/expo 2.1.3 → 2.3.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,164 @@
2
2
 
3
3
  All notable changes to `@testerpaykit/expo` are documented here.
4
4
 
5
+ ## 2.3.0 — 2026-11-18
6
+
7
+ - Exported `buildSheetMore` (+ types `SheetMore`, `SheetMoreInput`) for apps that compose `FloatingFeedbackButton` and `VoiceBugInputSheet` themselves.
8
+
9
+ ### Changed (one tap, one sheet — issue #5)
10
+ - A tap on the floating button always opens the report sheet
11
+ (`VoiceBugInputSheet`); the popup menu and the long press are gone (the
12
+ menu ran off the screen depending on where the button sat). The first tour
13
+ still comes with the very first tap, the daily briefing before the sheet
14
+ when due; where they opened the menu they now open the sheet.
15
+ - The sheet starts with speaking the bug, or, with `reportMode: 'form'`, with
16
+ a write button instead of the mic ("Lieber tippen" is hidden then).
17
+ - A bar at the bottom of the sheet (only while idle): equal tiles "Was
18
+ testen?" / "What to test" with the open count (only when the checklist has
19
+ tasks; otherwise "Nachtests" / "Retests" with the pending count), "Meine
20
+ Bugs" / "My Bugs", "Nachrichten" / "Messages" with the unread count, and
21
+ "Alles" / "All" (badge: the retest count while the checklist tile is
22
+ shown). Tiles: icon over label, red badge top right, test IDs
23
+ `tpk-sheet-checklist|retests|bugs|messages|all`.
24
+ - "Alles" shows a page with "Zurück zum Melden" / "Back to report" and every
25
+ former menu entry as a scrollable list (handle, role line, confirmed
26
+ earnings, then the entries in the old order). A tile or list entry closes
27
+ the sheet first and runs its action after the close (400 ms).
28
+ - Layout: the sheet is solid (host text no longer shows through the title)
29
+ except while recording; the category chips scroll sideways instead of
30
+ being cut off ("Probl…"); the four one-tap buttons are equal in a 2×2
31
+ grid. `sheetOpacity` now only sets the scrim.
32
+ - Accessibility: label "TesterPayKit", hint "Tippen, um einen Bug zu melden
33
+ oder mehr zu sehen." / "Tap to report a bug or see more."; no named
34
+ actions. Tour: "Die Leiste unten im Fenster hat alles Weitere." / "The bar
35
+ at the bottom of the sheet has everything else."
36
+
37
+ ### Added (Login with TPK: tester identity and test persona)
38
+ - Connect dialog reworked: "Wer testet hier?" / "Who is testing?" with three
39
+ reassurances (your sign-in stays, nothing to type, works for every app you
40
+ test through TesterPayKit), primary "Mit TPK verbinden" / "Connect with
41
+ TPK", secondary "Nicht jetzt" / "Not now". The link, app opening and
42
+ polling are unchanged. TPK is only the tester identity; the host app's own
43
+ sign-in stays as it is.
44
+ - Role picker right after a successful connect (`PersonaFlow`): "Verbunden
45
+ als <name>", "Aus wessen Sicht testest du?"; "Ich selbst" / "Myself"
46
+ first and the default, the developer's suggestions next with a
47
+ "vorgeschlagen" / "suggested" badge, then the rest. `PUT
48
+ /v1/testers/me/personas` only when the choice changed. Briefing card
49
+ ("Deine Rolle für diesen Test", "Achte besonders auf", privacy line,
50
+ "Los geht's") for a made-up role; skipped for "Myself". `GET` 404 or
51
+ offline skips the picker silently.
52
+ - Entry "Rolle wählen" / "Choose role" in the sheet's "Alles" list (once the
53
+ roles loaded) and the hint "Du testest als <Titel> (gespielt)" / "Testing
54
+ as <title> (played)" in that list and next to the button while a role is
55
+ chosen. `FloatingFeedbackButton`: new `personaTitle`.
56
+ - Host-app API, test builds only: `tpk.persona` (`{ id, title, attributes }`,
57
+ title in the device language, `null` for "Myself" and always in a `store`
58
+ build), `tpk.onPersonaChange(listener)`, `useTpkPersona(client)`,
59
+ `tpk.loadPersonas()`, `tpk.choosePersona(id | null)`. In a `store` build
60
+ no persona request is sent. Types `TpkPersona`, `PersonaCatalog`,
61
+ `PersonaOption`, `PersonaText`; component `PersonaFlow`.
62
+
63
+ ### Removed
64
+ - The connect dialog's "Noch keine TPK-App?" / "No TPK app yet?" link and
65
+ its ✕: the primary button already falls back to the web page when no app
66
+ takes the scheme, and "Nicht jetzt" closes.
67
+
68
+ ### Breaking
69
+ - `FloatingFeedbackButton` is now only the button: props `onOpen` (replaces
70
+ `onReportBug`), `onDailyBriefing(openSheet)`, `onTourShown`,
71
+ `unreadMessageCount`, `notificationCount`, `personaTitle`, `position`,
72
+ `style`, `testID`, `enableFirstTapTour`, `tourStorage`. All menu props
73
+ (`onGeneralFeedback`, `onDetailedReport`, `onViewDashboard`,
74
+ `onShowMyMoney`, `testerHandle`, `onMenuOpened`, `onEndSession`,
75
+ `onShowRetests`, `retestCount`, `onShowDebugLogs`, `onShowMyBugs`,
76
+ `onShowSessionDetails`, `onShowMessages`, `onAutoTest`, `onShowChecklist`,
77
+ `checklistCount`, `onShowPersona`, `onSendToClaude`, `onToggleLiveLink`,
78
+ `liveLinkConnected`, `voiceFirst`, `onFlushCachedCrashes`,
79
+ `confirmedEarnings`) are gone; the wrapper feeds the sheet instead.
80
+ `onLongPressVoiceBug` is gone too.
81
+ - `VoiceBugInputSheet`: new optional `more` (bar and list, built by the
82
+ wrapper) and `formFirst`.
83
+ - Removed: the first-time menu hint and its storage key
84
+ `tpk-fab-menu-hint-seen` (`hasSeenFabMenuHint`, `markFabMenuHintSeen`,
85
+ `FAB_MENU_HINT_MS`), the strings `menuOpen`, `menuClose`, `fabTapAction`,
86
+ `fabLongPressAction`, `fabMenuHint`; `fabA11yHint` is a plain string.
87
+
88
+ ## 2.2.0 — 2026-11-15
89
+
90
+ ### Changed (voice first)
91
+ - `TesterPayKitWrapper`: "Report Bug" and shake open the voice sheet; the
92
+ spoken draft lands on review. New `reportMode` prop (`'voice'` default,
93
+ `'form'` for the form first).
94
+ - `FloatingFeedbackButton`: new `onDetailedReport` adds "Report in detail"
95
+ (the form) above "End session".
96
+ - `VoiceBugInputSheet`: new `onTypeInstead` shows "Type instead" before
97
+ recording and after a failed one; the wrapper opens the form on the
98
+ details step.
99
+
100
+ ### Breaking
101
+ - **SMS confirmation removed.** A tested app no longer asks for a phone number
102
+ or an SMS code. `startPhone()` and `confirmPhone()` are gone, and so are the
103
+ number and code steps of `PhoneConfirmSheet`. Its `tpk` prop now needs
104
+ `linkWithTpkApp` and `checkAppLink`, and `onDone` gets only
105
+ `awaitingApproval`.
106
+ - **Release builds are inert unless built with channel `beta`.** TesterPayKit
107
+ now runs only in beta builds (TestFlight, Google Play test tracks); App Store
108
+ Guideline 2.2 forbids beta-testing features in a store build, and App Review
109
+ runs in the StoreKit sandbox too, so no runtime signal can tell them apart.
110
+ The channel is fixed at build time by the config plugin (`channel` prop, else
111
+ the `TPK_CHANNEL` environment variable of the build). Without one, `__DEV__`
112
+ builds count as `beta` and release builds as `store`. In a `store` build
113
+ `TpkExpo.init()` resolves to `null` (its return type is now
114
+ `Promise<TpkExpo | null>`) without any network call or storage write,
115
+ `TesterPayKitProvider` renders its children with `client: null`, and
116
+ `TesterPayKitWrapper` renders its children unchanged.
117
+ - **The config plugin adds the microphone only to beta builds.** With channel
118
+ `store` or none, `NSMicrophoneUsageDescription` and `RECORD_AUDIO` are no
119
+ longer added. Any other channel value fails the build. The plugin now needs
120
+ `expo` and `expo-constants` (both ship with every Expo app; new peer
121
+ dependencies).
122
+
123
+ ### Added
124
+ - **`<TpkVersionCheck projectId=… />`: update hint with a link to the store
125
+ and "what's new"** once per installed version, from the store releases
126
+ kept in TesterPayKit. Runs in beta and store builds without
127
+ `TpkExpo.init()`; one anonymous request
128
+ (`GET /public/apps/{projectId}/release`), no personal data, silent on any
129
+ error or after 5 s. A required update cannot be dismissed; "Später" /
130
+ "Later" waits for the next store version; "what's new" never shows on a
131
+ fresh install. Also exported: `fetchVersionNotice`, `decideVersionNotice`,
132
+ `dismissVersionUpdate`, `TpkWhatsNewSheet` and the `TpkVersionNotice`
133
+ type.
134
+ - **`getBuildChannel()` and `TpkExpo.channel`** return the build channel
135
+ (`'beta' | 'store'`, type `TpkBuildChannel`), so apps can hide their own
136
+ TesterPayKit entries in store builds. The plugin writes it to
137
+ `extra.testerpaykit.channel`.
138
+ - **Google Play refuses beta builds in production.** A beta build's Android
139
+ manifest gets the meta-data
140
+ `com.google.android.play.largest_release_audience` = `NONPRODUCTION`.
141
+ - **Confirm once with the TPK app.** The sheet behind `openVerification()`
142
+ says "Einmal mit der TPK-App bestätigen" / "Confirm once with the TPK app".
143
+ Its button creates a link (`tpk.linkWithTpkApp()`, POST
144
+ `/v1/testers/me/phone/link` with project and platform) and opens the TPK app,
145
+ or the web page when the app is missing ("Noch keine TPK-App?" opens the web
146
+ page directly). The sheet then asks the server every 2 s and whenever the
147
+ app comes back to the front (`tpk.checkAppLink()`), for at most 15 minutes.
148
+ Confirmed: it closes, the widget appears and queued reports go out. Not
149
+ approved yet: the waiting-for-approval note. Closing the sheet stops asking.
150
+ - **Version check.** Every request to the TesterPayKit API (also uploads,
151
+ polling, the live link and AI-run sockets, and the version notice) carries
152
+ `X-TPK-Client: expo/<version>` (`TPK_CLIENT_ID`). When the server answers
153
+ 426 `client_outdated` (this SDK is below its minimum), the SDK sends
154
+ nothing more for this app run: requests are refused locally without
155
+ throwing into the app, periodic flushes stop, and queued reports stay
156
+ queued for the new build. `TesterPayKitWrapper` tells the tester once:
157
+ "TesterPayKit in dieser App ist zu alt (Version {yours}, nötig {min}).
158
+ Bitte installiere die neue Testversion." / "TesterPayKit in this app is
159
+ too old ({yours}, needs {min}). Please install the new test build."
160
+ Read the state with `getClientOutdated()`, `onClientOutdated(listener)` or
161
+ the hook `useTpkClientOutdated()`. The public version notice keeps working.
162
+
5
163
  ## 2.1.3 — 2026-11-09
6
164
 
7
165
  - No change of its own. Follows the release train, which moved for a fix in the
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',
@@ -138,8 +193,7 @@ function FeedbackControls() {
138
193
  return (
139
194
  <>
140
195
  <FloatingFeedbackButton
141
- disabled={!ready}
142
- onPress={() => setOpen(true)}
196
+ onOpen={() => ready && setOpen(true)}
143
197
  />
144
198
  <BugReportSheet
145
199
  currentScreen="Home"
@@ -172,7 +226,8 @@ into `TesterPayKitProvider` instead of `config`.
172
226
 
173
227
  `<TesterPayKitWrapper>` shows its button, shake-to-report, the voice flow
174
228
  and every tester sheet **only** for a tester with a confirmed phone number
175
- **and** an admin's approval — in every build, TestFlight included.
229
+ **and** an admin's approval — in every build, TestFlight included. The
230
+ number is confirmed once in the TesterPayKit app, never by SMS in your app.
176
231
  Everyone else sees your app and nothing from TesterPayKit.
177
232
 
178
233
  ```ts
@@ -183,14 +238,52 @@ await tpk.refreshAccess(); // re-asks the server (offline keeps the cache)
183
238
  await tpk.openVerification(); // your own "Become a tester" entry
184
239
  ```
185
240
 
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
241
+ `openVerification()` opens the wrapper's connect dialog "Wer testet hier?" /
242
+ "Who is testing?" when the number is not confirmed yet. Its button "Mit TPK
243
+ verbinden" / "Connect with TPK" 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; "Nicht jetzt" /
246
+ "Not now" closes it. It says so when the approval is pending. TPK is only
247
+ the tester's identity here: your app's own sign-in stays as it is, and
248
+ nothing is typed into your app. Access is
188
249
  re-checked whenever the app comes to the front; any 403
189
250
  `phone_required` / `approval_required` hides the widget at once. If you
190
251
  render `<TpkOnboarding>` or `<TpkWelcomeSheet>` yourself, render them only
191
252
  while `tpk.access === 'ready'`.
192
253
 
193
- Wrapper options for the menu: `enableTesterDashboard` (default true),
254
+ ### Login with TPK: test persona
255
+
256
+ Right after a successful connect, the wrapper shows a picker "Aus wessen
257
+ Sicht testest du?" / "Whose eyes are you testing with?". "Ich selbst" /
258
+ "Myself" is always the first row and the default; the roles the developer
259
+ suggested come next with a "vorgeschlagen" / "suggested" badge, then the
260
+ rest of the catalog. The tester decides; the developer can only suggest.
261
+ A made-up role opens a briefing card (the role, what to watch for, and the
262
+ note that the app sees only this role and that reports are marked
263
+ "gespielt"); "Ich selbst" skips it. Later the entry "Rolle wählen" /
264
+ "Choose role" in the sheet's "Alles" list opens the picker again, and while a role is chosen the overlay
265
+ says "Du testest als <Titel> (gespielt)" / "Testing as <title> (played)".
266
+ Reports and sessions carry the role on the server; the payloads need no
267
+ change. Not in the project yet (404) or offline: the picker is skipped
268
+ silently.
269
+
270
+ Your app may read the chosen role **in test builds only** (channel `beta`)
271
+ to prepare matching test data. It is made-up data, never anything real
272
+ about the tester. In a `store` build it is always `null` and the SDK sends
273
+ no persona request at all.
274
+
275
+ ```ts
276
+ tpk.persona; // { id, title, attributes } | null
277
+ // title: German on German devices, else English
278
+ // null = "Myself", not known yet, or a store build
279
+ tpk.onPersonaChange(() => …); // returns the unsubscribe
280
+ const persona = useTpkPersona(client); // hook, re-renders on change; client may be null
281
+
282
+ await tpk.loadPersonas(); // { current, persona, personas } | null (never throws)
283
+ await tpk.choosePersona(id); // PUT; id = null for "Myself"; throws when offline
284
+ ```
285
+
286
+ Wrapper options for the sheet's "Alles" list: `enableTesterDashboard` (default true),
194
287
  `showCompensation` (default true — false hides every amount, the money
195
288
  block of the daily briefing and the bug-bonus hint), `showDebugLogs`
196
289
  (default `__DEV__`).
@@ -201,8 +294,17 @@ tasks). Unread messages show as a yellow number on the FAB, new bug news
201
294
  as a banner for six seconds, and every submit ends with a thank-you that
202
295
  names the tester.
203
296
 
297
+ A tap on the button always opens one report sheet (no long press, no popup
298
+ menu). It starts with speaking the bug, or with a write button when
299
+ `reportMode="form"`. A bar at the bottom holds "Was testen?" (or "Nachtests"
300
+ while the checklist is empty), "Meine Bugs", "Nachrichten" and "Alles", which
301
+ switches the sheet to the list of everything else (feedback, money, session,
302
+ roles, live link, "Zurück zum Melden" to go back).
303
+
204
304
  ## What `TpkExpo.init()` does
205
305
 
306
+ 0. In a `store` build: nothing. It resolves to `null` (see
307
+ [Beta and store builds](#beta-and-store-builds)).
206
308
  1. Reads cached anonymous-tester JWT from AsyncStorage (key
207
309
  `@testerpaykit/auth`). If the cached entry matches the current
208
310
  `projectId` + `testerCode`, reuse it — skip the network round
@@ -359,7 +461,7 @@ if (note) {
359
461
 
360
462
  ## Language
361
463
 
362
- Menu, bug report and voice sheet speak German on German devices and
464
+ Report sheet, bug report and voice sheet speak German on German devices and
363
465
  English everywhere else (device language via `expo-localization`). To
364
466
  pin one language for all testers:
365
467
 
@@ -372,6 +474,90 @@ pin one language for all testers:
372
474
  Standalone sheets outside the wrapper take the same setting from
373
475
  `<TpkLanguageProvider language="de">`.
374
476
 
477
+ ## Update hint and "what's new"
478
+
479
+ `<TpkVersionCheck>` works in **both** channels, also in store builds where
480
+ `TpkExpo.init()` returns `null` and the rest of TesterPayKit is off. It
481
+ needs no `init`. It sends one anonymous request with the project id,
482
+ platform, installed version and language (no token, no device data,
483
+ nothing stored) and shows at most one thing:
484
+
485
+ - a **required update**: a dialog that only leads to the store;
486
+ - an **available update**: once per new store version, with "Later";
487
+ - otherwise **"what's new"** for the installed version, once, but not on
488
+ the first start of a fresh install.
489
+
490
+ ```tsx
491
+ import { TpkVersionCheck } from '@testerpaykit/expo';
492
+
493
+ export default function RootLayout() {
494
+ return (
495
+ <>
496
+ <Stack />
497
+ <TpkVersionCheck projectId="<project-uuid>" />
498
+ </>
499
+ );
500
+ }
501
+ ```
502
+
503
+ It checks once on mount. The installed version comes from
504
+ `expo-application` (`nativeApplicationVersion`), else from the app config
505
+ (`expo-constants`); the language from `TpkLanguageProvider` or the device.
506
+ The seen and dismissed versions live in AsyncStorage
507
+ (`tpk_version_notice_seen`, `tpk_version_notice_dismissed`); pass
508
+ `storage` to use your own `TpkStorage`.
509
+
510
+ The app never updates itself; the button opens the App Store, Google Play
511
+ or web page set for the release (`Linking.openURL`). Store releases
512
+ (version, notes in German and English, store link, required) are kept per
513
+ platform in the console, with `tpk release add` or the API. iOS, Android
514
+ and web are supported; other platforms get no notice. Any network or
515
+ parse error, or no answer within 5 seconds, shows nothing.
516
+ `fetchVersionNotice({ projectId })` returns the raw `TpkVersionNotice` if
517
+ you want to render it yourself (with `decideVersionNotice` and
518
+ `dismissVersionUpdate` for the once-per-version rules), and
519
+ `<TpkWhatsNewSheet notice={…} visible onClose={…} />` shows "what's new"
520
+ on demand, e.g. from a settings row.
521
+
522
+ Store review: mention the update hint and "what's new" in the review
523
+ notes. List no collected data for it in the App Privacy section or Google
524
+ Play's Data safety form: the request carries no personal data and is not
525
+ stored.
526
+
527
+ ## Version check
528
+
529
+ Every request to the TesterPayKit API carries `X-TPK-Client: expo/<version>`
530
+ (exported as `TPK_CLIENT_ID`): the REST calls, uploads, polling, the live
531
+ link and AI-run sockets, and the version notice. The server keeps a minimum
532
+ version per client kind. Below it, it answers **426** `client_outdated`
533
+ with `{ kind, min, yours, message }`.
534
+
535
+ From the first 426 on, this app run is **outdated**:
536
+
537
+ - the SDK sends nothing more: requests are refused before they reach the
538
+ network, without throwing into your app; periodic flushes stop;
539
+ - reports submitted now, and those already queued, stay in the queue for
540
+ the new build (`submitBug` returns `outcome: 'queued'`);
541
+ - `TesterPayKitWrapper` shows the tester a notice once, until tapped away:
542
+ "TesterPayKit in dieser App ist zu alt (Version 2.2.0, nötig 2.3.0).
543
+ Bitte installiere die neue Testversion." / "TesterPayKit in this app is
544
+ too old (2.2.0, needs 2.3.0). Please install the new test build."
545
+
546
+ Store builds never see this: there TesterPayKit sends nothing at all. The
547
+ public version notice (`<TpkVersionCheck>`, `/public/**`) is never refused
548
+ and keeps working in an outdated app.
549
+
550
+ ```tsx
551
+ import {
552
+ getClientOutdated,
553
+ onClientOutdated,
554
+ useTpkClientOutdated,
555
+ } from '@testerpaykit/expo';
556
+
557
+ const outdated = useTpkClientOutdated(); // null, or { kind, min, yours, message }
558
+ const off = onClientOutdated((info) => log(info.min));
559
+ ```
560
+
375
561
  ## AI test runs started from outside
376
562
 
377
563
  The wrapper can hand the app to an AI tester that a coordinator starts
@@ -395,8 +581,8 @@ The project's organisation must have AI features enabled.
395
581
 
396
582
  ## Live link to Claude Code
397
583
 
398
- For the developer's own device (dev build, TestFlight): two menu items
399
- connect the running app to the developer's Claude Code session.
584
+ For the developer's own device (dev build, TestFlight): two entries in the
585
+ sheet's "Alles" list connect the running app to the developer's Claude Code session.
400
586
 
401
587
  ```tsx
402
588
  <TesterPayKitWrapper tpk={tpk} enableLiveLink>
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;