testerpaykit 1.2.0

In-app bug reports for TesterPayKit testers — screenshots, recordings and voice notes, crash capture, sessions and engaged minutes.

Changelog

All notable changes to TesterPayKit will be documented in this file.

The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.

1.2.0 - 2026-11-01

Changed

• Same version number as all TesterPayKit SDKs (Flutter, Expo, Swift, Web) from now on: one release train, one feature set. No functional change against the previous version.

0.9.0 - 2026-10-31

Added

• Live link to Claude Code (opt-in, TesterPayKitWrapper(enableLiveLink: true)). Two new items in the TPK menu: "Connect to Claude" keeps a WebSocket to the API while the app is in front, so the developer's Claude Code session can ask what the screen shows (MCP device_snapshot: screenshot, every text and field value, current screen, navigation, breadcrumbs, logs). "Send to Claude" captures the screen, asks for one line and sends it as a note (MCP list_device_notes / get_device_note). Extra app state for both: TesterPayKit.instance.liveStateProvider. The choice survives app restarts; the socket closes when the app goes to the background. Needs the API from 2026-10-31.
• Claude can drive the app over the live link: tap (by visible text or by x/y in points), type (into the field with that label, or the focused one, optionally pressing done), scroll and back (MCP device_tap / device_type / device_scroll / device_back). Works on the semantics tree; the AI tester's deny list (delete account, pay now, sign out …) applies and TesterPayKit's own button and panels are never a target. A short hint on the device ("Claude taps: Save") shows what happened. Needs the API from 2026-11-01.
• "What to test" in the TPK menu (shown when the project has a checklist): the tester picks a task, walks its steps with ✓ / ✗ and an optional note (asked for once on ✗), and sends the run (GET /v1/testers/me/checklist, POST /v1/testers/me/checklist/<taskId>/runs, API from 2026-11-01). The steps sit in a small panel at the bottom that does not block the app and folds down to one line. The list shows the tester's last result per task. ApiClient.getChecklist / submitChecklistRun.

Changed

• The remote AI-run claim sends the app version, so an AI retest of a fixed bug reaches this app only from the fixed build on.
• The voice bug sheet no longer darkens the app behind it: the scrim is almost clear, so the tester sees the screen they describe while recording.

0.8.0 - 2026-10-30

Added

• Quick actions in the voice sheet: "Doesn't work", "Don't get it", "Looks broken", "Something's missing". One tap sends the screenshot taken before the sheet opened, the API drafts the report (POST /v1/testers/me/bug-reports/quick-draft, API from 2026-10-28), and the tester reviews it before submitting. Same four buttons as the Expo SDK. ApiClient.quickDraftBug.
• German and English tester surface, chosen by device language (German devices get German, all others English). Before, menu, tour, retests and voice sheet mixed both. TesterPayKitWrapper(language: TpkLanguage.de) pins one; TpkLanguage is exported. Money shows as "1,00 €" in German and "€1.00" in English.

Changed

• The workboard shows only real data: the tester's assigned tasks, the app's own version and build, and focus areas / build notes only when the host passes them. It used to fill empty parameters with invented sample tasks, fixes and focus areas. The "View All Tasks" button that only said "coming soon" is gone.

Removed

• MockTestData (the invented workboard data).

Fixed

• The end-of-session dialog showed earnings in dollars while the floating button and session details showed euros.
• The voice sheet scrolls instead of overflowing on short screens.
• Flutter web works. TesterPayKit.initialize failed on every web app because the local database expected sqlite3.wasm and drift_worker.js in the host's web/ folder. Both now ship with the SDK as web-only assets, so nothing has to be copied.
• Web: the voice bug report crashed right after the microphone prompt (it needed a temp directory). It now records Opus/WebM in memory.
• Web: saving an annotated screenshot crashed (it wrote a file), and screen recording threw on Platform.
• Web: screenshots, voice notes and the network log are now uploaded with the report instead of being dropped.
• After saving an annotated screenshot the bug report dialog closed again instead of coming back (the editor popped twice).

Note

• A web app served from its own domain needs that origin entered in the project settings (web origins), otherwise the browser blocks every API call (CORS).

0.7.0 - 2026-10-28

Added

• Retests judged step by step. RetestItem.acceptanceSteps carries the bug's acceptance steps (needs an API from 2026-10-28). The retest detail lists them with 👍/👎 per step; "Verified" stays disabled until every step passed, and the verdicts go along with verifyRetest(bugId, stepVerdicts:) / reopenRetest(bugId, stepVerdicts:). Bugs without acceptance steps work as before.
• Debug builds print a note when the API reports a newer testerpaykit release than the one running, with the update command. The API also mails the project's coordinator once per release and shows a notice on the project page in the console.

0.6.0 - 2026-10-25

Added

• AI test runs started from outside. TesterPayKitWrapper(aiRemoteTrigger: true) polls POST /v1/testers/me/ai-sessions/claim every aiRemotePollSeconds (default 15) while the app is resumed and no AI run is open. A run started in the console or with tpk autotest opens straight away — no persona picker, no coordinator token in the build — and the overlay closes itself 3 s after the run ends. ApiClient.claimRemoteAiSession(projectId) returns the claimed RemoteAiSession or null.
• The AI tester can type: the type action fills a text field through SemanticsAction.setText (focusing it first). Same deny list and overlay exclusion as tap; an obscured field accepts text, but its value never reaches the model.
• AiRemoteControl takes remoteSession, captureScreenshot and onSessionEnded; apiBaseUrl, coordinatorToken and projectId are now only needed for runs started in the app.

Fixed

• The AI model now gets a screenshot on every step. Before, the Flutter SDK replied with the widget list only, so the model could not see whether a tap changed anything. The capture is the masked app area (TesterSensitive regions stay hidden) at logical-pixel size.
• A step's screenshot waits at most 5 s. When the app drew no frames, the capture used to block the whole discover_widgets reply, and the server ended the run after 10 s.
• The AI could pick the Stop button of its own overlay and the TesterPayKit button as widgets to tap. Both are now hidden from it.

0.5.0 - 2026-10-21

0.4.3 was prepared but never published; its changes ship here.

Changed

• Dependencies to their latest majors: file_picker ^13.1.0, record ^7.1.2, pro_image_editor ^13.5.0, json_annotation ^4.12.0. Host apps that pin older majors of these need to move up too. pro_image_editor stays on 13: version 14 moves to material_ui, and hosts on the regular Material library would crash in the annotation editor without extra localization setup.
• flutter_riverpod is no longer a dependency. The SDK never used it; the ^2.6.1 constraint only blocked host apps on Riverpod 3.
• Bug-report repro steps reorder through onReorderItem (the onReorder callback is deprecated since Flutter 3.41).
• README rewritten: correct quick start (the old one used config fields that don't exist), invite-only account note, honest platform list (Android, iOS) and the commercial licence instead of "MIT".
• file_picker constraint raised from ^12.0.0-beta.3. Host apps that pinned file_picker to a 12.0 beta as a workaround for the build failure below can drop the pin.

Added

• ApiClient.getMyPoints() — the calling tester's total points and leaderboard rank (GET /v1/testers/me/points).
• ApiClient.submitDemandSignal(...) — the tester's "would you use / pay for / recommend it?" answers for a session they tested (POST /v1/testers/me/demand-signals, upserts per session).

Fixed

• Host-app builds failed once file_picker resolved to 12.3.0. The old ^12.0.0-beta.3 range let a plain flutter pub upgrade pick 12.3.0. That release removed FilePickerResult: pickFiles() returns the list itself, and PlatformFile no longer has size or bytes. flutter build then aborted in kernel_snapshot_program with "The getter 'files' isn't defined for the type 'List
• The reference-screenshot picker did nothing on iOS and Android. It read PlatformFile.bytes without withData: true, and that field is only filled on web, so the picked image was dropped without a message. It now loads the image with readAsBytes() on every platform.

0.4.2 - 2026-07-10

Changed

• Screen recording now uses moinsen_screen_recording instead of the unmaintained flutter_screen_recording 2.0.25. Upstream declared two dead / unreachable Gradle repositories (jcenter() + a bytedance.com maven) that break a Gradle 9 app build. The fork removes exactly those two (keeping the native HBRecorder recorder on jitpack, injected by the plugin so apps still need no repo config). One SDK bump lifts Gradle 9 compatibility for every app that embeds TesterPayKit — no per-app gradle changes. Verified: the SDK example builds on both Gradle 8.12 and Gradle 9.0.0 (AGP 8.11.1). The recorder's Dart/iOS API is unchanged.

0.4.1 - 2026-06-22

Fixed

• Tester dashboard crash under MaterialApp.builder / MaterialApp.router mounts. The inline "Welcome, Tester!" dashboard was returned outside the host Navigator, so opening its in-screen About dialog (showAboutDialog(useRootNavigator: false)) asserted with "Navigator operation requested with a context that does not include a Navigator" on hosts that mount the wrapper above their Navigator (e.g. go_router via MaterialApp.router). TesterPayKitWrapper now wraps the inline dashboard in its own Navigator, restoring the nearest-Navigator ancestor its modals need — without re-introducing a theme-overriding MaterialApp (which had previously broken dark mode). The host-provided navigatorKey only backed wrapper-pushed routes, not the dashboard's own modals, so this closes that gap.

0.4.0 - 2026-06-03

Consolidated entry — the CHANGELOG had drifted (last entry 0.1.0 while the reported sdk_version was hardcoded inconsistently at 0.1.0/0.2.0). This release introduces a single source of truth (kTpkSdkVersion, kept in sync with pubspec.yaml) and folds in the batches since 0.1.0.

Added

• In-widget notification feed: server auto-notifies the tester (bug accepted/fixed/rejected, retest assigned, reward) → "Nachrichten" inbox in the FAB with an unread badge.
• Runtime invite-code onboarding: TesterPayKit.loginAnonymous() (parity with the TS SDK) + InviteCodeScreen + persistence; gated by TesterPayKitConfig.enableInviteCodeOnboarding.
• Navigation flow in bugs: TpkNavigatorObserver + breadcrumb-based navigationFlow() ship the screen path that led to a bug (in appSnapshot.navigationPath).
• Activity-gated earnings, Session-Details + "Meine Bugs" screens, task-progress auto-detection ("X von Y erledigt"), AI-Tester (gesture injection + remote control), first-tap widget tour.

Changed

• sdk_version single source of truth — kTpkSdkVersion (lib/src/version.dart), used by the session + bug-report + submission paths; keep in sync with pubspec.yaml.
• Session lifecycle: background pauses (not ends) the session; foreground resumes; foreground-time clock drives engaged minutes.
• Durable payment pipeline: reconcile orphaned sessions on launch, periodic weekly-submission, client-idempotent retry.

Fixed

• Voice bugs on native (iOS/Android) now transmit the O-Ton transcript + sourceLanguage (were dropped in the native upload payload → tester_title/description/language stayed empty).
• environment detection recognises .local/.lan mDNS + all RFC-1918 private ranges as local (a dev build on http://*.local:18080 was mislabelled prod).
• Submission outbox JSON round-trip; branded screens readable on dark-host themes.

0.1.0 - 2025-11-05

Added - Phase 1: MVP Bug Reporting & Crash Handling

Bug Reporting

• Bug Report Dialog: Comprehensive dialog for reporting bugs with rich categorization
  • Type selection (bug, crash, UI issue, performance, feature request)
  • Severity levels (critical, high, medium, low)
  • Category classification (functional, UI, performance, security, data, network, crash, other)
  • Reproduction steps with frequency tracking
  • Expected vs actual behavior fields
  • Affected feature identification
• Shake-to-Report: Shake device gesture to instantly trigger bug report dialog
• Auto-Context Capture: Automatically captures device state, app state, and breadcrumbs
• Screenshot Support: Database schema ready for screenshot and screen recording attachments

Crash Handling

• Automatic Crash Detection: Flutter error and platform exception capture
• Post-Crash Reporting: Crash report dialog shown on next app launch
• Full Crash Context: Complete crash information including:
  • Stack traces
  • Device snapshots (OS, model, battery, network)
  • App snapshots (version, build, memory)
  • User journey breadcrumbs
• Battery Integration: Real-time battery level and charging state capture via battery_plus
• Network Integration: Network type and connectivity status via connectivity_plus
• Memory Tracking: Basic memory tracking structure (platform-specific implementation required)
• Crash Report Dialog: Post-crash dialog with optional notes and submission

Session Management

• Automatic Session Tracking: Start, end, duration, and activity metrics
• Session End Dialog: Structured feedback collection at session completion
  • Duration worked
  • Overall experience rating
  • Issues encountered count
  • Quality assessment
  • Free-form feedback
• Session Stats: Screen views, taps, and event counts
• Session Breadcrumbs: Complete user journey tracking

Tester Dashboard

• Daily Dashboard: One-time-per-day tester onboarding screen
• Test Tasks Display: Show assigned testing tasks with priorities
• Build Information: Display app version, build number, and environment
• Focus Areas: Highlight specific features to test
• Smart Persistence: SharedPreferences to track dashboard views

UI Components

• Floating Feedback Button: Always-accessible draggable button
  • Report bug action
  • General feedback action
  • View dashboard action
  • End session action
  • Notification badge with unreported items count
  • Smooth animations and haptic feedback
• TesterPayKitWrapper: Main wrapper widget that:
  • Shows dashboard on first daily launch
  • Provides floating feedback button
  • Handles shake gesture detection
  • Manages session lifecycle

Data Management

• SQLite Database: Fast, reliable local storage with Drift ORM
• Database Tables:
  • bug_reports - Detailed bug reports with all context
  • crash_contexts - Crash information and stack traces
  • breadcrumbs - User journey tracking
  • session_end_feedbacks - Session completion feedback
  • device_id_metadata - Device ID rotation management
  • events - Comprehensive event tracking
  • sessions - Session lifecycle tracking
• Schema Versioning: Automatic migrations from v1 → v2 → v3
• Device ID Rotation: Automatic 30-day device ID rotation for privacy
• Notification Counter: Real-time count of unreported crashes and draft bug reports

Privacy & Security

• Local-First Architecture: All data stored locally
• Device ID Management: Privacy-preserving device identification with automatic rotation
• GDPR Compliance: Privacy-first design principles
• No Tracking Without Consent: Explicit initialization required

Developer Experience

• Comprehensive Documentation: Full README with examples
• Type Safety: Freezed models for immutable data structures
• Error Handling: Robust error capture and reporting
• Logging: Optional debug logging via configuration

Dependencies

• drift (^2.23.0) - SQLite ORM
• battery_plus (^7.0.0) - Battery level detection
• connectivity_plus (^7.0.0) - Network connectivity
• device_info_plus (^11.1.0) - Device information
• shake (^3.0.0) - Shake gesture detection
• shared_preferences (^2.3.5) - Persistent storage
• freezed (^2.5.7) - Immutable models
• json_annotation (^4.9.0) - JSON serialization

Technical Details

• Flutter SDK: >=3.5.0
• Dart SDK: >=3.5.0
• Platforms: Android, iOS, Linux, macOS, Windows
• Database Schema Version: 3
• Lines of Code: ~8,500 (excluding generated files)

Known Limitations

• Screenshot capture deferred (requires app wrapper architectural changes)
• Memory tracking basic structure only (native implementation needed)
• API submission not yet implemented (data stored locally)

0.0.1 - 2025-10-15

Added

• Initial project structure
• Basic session tracking
• Event tracking foundation
• Database schema
• API client structure

---

For detailed usage instructions and examples, see README.md.