@testerpaykit/expo 0.4.1

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.
@@ -0,0 +1,2175 @@
1
+ import * as _testerpaykit_api_client from '@testerpaykit/api-client';
2
+ import { SessionEventInput, BugReportAttachmentInput, BugReportAttachmentResponse, BugReportPayload, BugReportResponse, TaskListResponse, TesterTask, TesterPayKitApiClient, AnonymousLoginResponse, BugReportType, BugSeverity, BugCategory, MyBugReportSummary, NotificationsResult, TesterSessionEndReason, TesterProfile, TesterPoints, EarningsSummary, PayoutRecord } from '@testerpaykit/api-client';
3
+ export { BugCategory, BugReportAttachmentInput, BugReportAttachmentResponse, BugReportType, BugSeverity, EarningsSummary, EnrollmentResponse, MyBugReportSummary, MyBugReportsResponse, NotificationsResult, PayoutRecord, TaskListFilter, TaskListResponse, TesterPoints, TesterProfile, TesterTask, TpkNotification } from '@testerpaykit/api-client';
4
+ import React, { RefObject, ReactNode } from 'react';
5
+ import { StyleProp, ViewStyle, TextStyle } from 'react-native';
6
+
7
+ interface PeriodFilter {
8
+ /** Inclusive lower bound. Omit to read from the start of buffer. */
9
+ start?: Date;
10
+ /** Exclusive upper bound. Omit to read to the end of buffer. */
11
+ end?: Date;
12
+ }
13
+ /** Aggregated session stats — same shape Flutter's SessionStats has,
14
+ * minus fields that only make sense with a relational store. */
15
+ interface SessionStatsSnapshot {
16
+ totalScreenViews: number;
17
+ totalTaps: number;
18
+ totalCustomEvents: number;
19
+ /** Distinct `screenRoute` values seen in events. */
20
+ uniqueScreens: number;
21
+ /** Time between first and last event timestamp, in minutes. 0 when
22
+ * the buffer holds <2 events or no events carry a timestamp. */
23
+ totalDurationMinutes: number;
24
+ }
25
+ /** Count events by their `eventType` field. Returns an empty object
26
+ * for an empty buffer. */
27
+ declare function getEventCounts(events: readonly SessionEventInput[], filter?: PeriodFilter): Record<string, number>;
28
+ /** Distinct `screenRoute` values seen in events. Order-preserving
29
+ * (first-seen first), so consumers can show "newest screen" by
30
+ * reading the tail. */
31
+ declare function getUniqueScreens(events: readonly SessionEventInput[], filter?: PeriodFilter): string[];
32
+ /** Snapshot of in-buffer session activity. */
33
+ declare function getSessionStats(events: readonly SessionEventInput[], filter?: PeriodFilter): SessionStatsSnapshot;
34
+
35
+ interface TpkStorage {
36
+ get<T = unknown>(key: string): Promise<T | null>;
37
+ set(key: string, value: unknown): Promise<void>;
38
+ remove(key: string): Promise<void>;
39
+ keys?(): Promise<string[]>;
40
+ }
41
+ declare class ExpoStorage implements TpkStorage {
42
+ /**
43
+ * Read a JSON-serializable value, returning `null` if the key is
44
+ * absent or the stored value can't be parsed.
45
+ */
46
+ get<T = unknown>(key: string): Promise<T | null>;
47
+ set(key: string, value: unknown): Promise<void>;
48
+ remove(key: string): Promise<void>;
49
+ /**
50
+ * List every key this SDK has written. Useful for inspection /
51
+ * debug dashboards; not used internally.
52
+ */
53
+ keys(): Promise<string[]>;
54
+ }
55
+
56
+ interface Breadcrumb {
57
+ /** ISO timestamp at the time the action happened. */
58
+ t: string;
59
+ /** Action category: 'tap' | 'navigation' | 'http' | 'custom' | 'crash' | 'log'. */
60
+ action: string;
61
+ /** Free-form short label, e.g. 'sign_up_button' or 'GET /bons'. */
62
+ target?: string;
63
+ /** Optional screen / route the user was on. */
64
+ screen?: string;
65
+ /** Optional context map (small object, no large payloads). */
66
+ data?: Record<string, unknown>;
67
+ }
68
+ interface BreadcrumbsOptions {
69
+ /** Max entries to keep in the ring. Default 50. */
70
+ maxEntries?: number;
71
+ }
72
+ declare class Breadcrumbs {
73
+ private readonly maxEntries;
74
+ private readonly buffer;
75
+ private readonly pending;
76
+ constructor(options?: BreadcrumbsOptions);
77
+ /** Record a breadcrumb. Drops the oldest if past capacity. */
78
+ record(crumb: Omit<Breadcrumb, 't'>): void;
79
+ /** Snapshot of the current buffer (cloned). */
80
+ snapshot(): Breadcrumb[];
81
+ /** Breadcrumbs not yet flushed to the session timeline endpoint. */
82
+ pendingSnapshot(): Breadcrumb[];
83
+ /** Mark the oldest pending breadcrumbs as successfully flushed. */
84
+ markPendingFlushed(count?: number): void;
85
+ /** Clear the buffer — typically called after a successful submit. */
86
+ clear(): void;
87
+ }
88
+
89
+ interface CrashHandlerOptions {
90
+ /** Called when a crash is captured. Return value awaited. */
91
+ onCrash: (info: CrashInfo) => Promise<void> | void;
92
+ /** Optional breadcrumbs buffer — appended to the report. */
93
+ breadcrumbs?: Breadcrumbs;
94
+ /** Forward to the previous ErrorUtils handler (default true). */
95
+ chainPrevious?: boolean;
96
+ }
97
+ interface CrashInfo {
98
+ /** Error message / `toString()` of the thrown value. */
99
+ message: string;
100
+ /** Stack trace if available. */
101
+ stack?: string;
102
+ /** Did the error reach the JS runtime as fatal? */
103
+ isFatal: boolean;
104
+ /** Snapshot of breadcrumbs at the time of crash (newest last). */
105
+ breadcrumbs?: Breadcrumb[];
106
+ }
107
+ /**
108
+ * Install the global handler. Returns a teardown function that
109
+ * restores the previous handler — call it in test environments to
110
+ * avoid bleeding handlers between cases.
111
+ */
112
+ declare function installCrashHandler(options: CrashHandlerOptions): () => void;
113
+
114
+ interface CachedCrash {
115
+ /** Local id for review / retry bookkeeping. */
116
+ id: string;
117
+ /** ISO timestamp when the crash was captured. */
118
+ capturedAt: string;
119
+ /** Captured JS crash context. */
120
+ info: CrashInfo;
121
+ }
122
+ declare class CrashQueue {
123
+ private readonly storage;
124
+ constructor(storage: TpkStorage);
125
+ enqueue(info: CrashInfo): Promise<CachedCrash>;
126
+ pending(): Promise<CachedCrash[]>;
127
+ size(): Promise<number>;
128
+ remove(id: string): Promise<void>;
129
+ private read;
130
+ }
131
+
132
+ interface QueuedEntry {
133
+ /** Local id (uuid) for queue bookkeeping. Distinct from server id. */
134
+ id: string;
135
+ /**
136
+ * Client-supplied idempotency key (UUIDv4) — sent as the
137
+ * `X-Idempotency-Key` header on every retry of this entry. The
138
+ * server matches it against `bug_reports.idempotency_key` (partial
139
+ * unique index, see migration 027) and returns the existing row
140
+ * with `deduplicated: true` instead of inserting a duplicate. This
141
+ * is what fixed the 2026-05-28 retry-storm where one queued bug
142
+ * resurrected as 2+ rows after a server-side schema fix. Optional
143
+ * on read for back-compat with queue entries written by older SDKs.
144
+ */
145
+ idempotencyKey?: string;
146
+ /** ISO timestamp when the entry was first queued. */
147
+ queuedAt: string;
148
+ /** Last error message — surfaced in logs but not sent to server. */
149
+ lastError?: string;
150
+ /** The submit payload, unchanged. */
151
+ payload: BugReportPayload;
152
+ }
153
+ interface QueueFlushOptions {
154
+ /**
155
+ * Submit function — usually a closure around `api.submitBugReport`
156
+ * that forwards the idempotency key as the `X-Idempotency-Key`
157
+ * header. Receives the same key on every retry of the same queue
158
+ * entry so the server can dedup.
159
+ */
160
+ submit: (p: BugReportPayload, options?: {
161
+ idempotencyKey?: string;
162
+ }) => Promise<BugReportResponse>;
163
+ /** Called per successful submit; useful for telemetry. */
164
+ onSuccess?: (entry: QueuedEntry, response: BugReportResponse) => void;
165
+ /** Called per permanent failure (4xx). */
166
+ onPermanentFailure?: (entry: QueuedEntry, error: unknown) => void;
167
+ }
168
+ interface QueueFlushResult {
169
+ attempted: number;
170
+ succeeded: number;
171
+ permanentFailed: number;
172
+ transientFailed: number;
173
+ }
174
+ interface QueuedAttachmentEntry {
175
+ /** Local id (uuid) for queue bookkeeping. Distinct from server id. */
176
+ id: string;
177
+ /** Server bug-report id this attachment belongs to. */
178
+ bugReportId: string;
179
+ /** ISO timestamp when the entry was first queued. */
180
+ queuedAt: string;
181
+ /** Last error message — surfaced in logs but not sent to server. */
182
+ lastError?: string;
183
+ /** Attachment payload, including base64 data or file reference. */
184
+ attachment: BugReportAttachmentInput;
185
+ }
186
+ interface AttachmentQueueFlushOptions {
187
+ /** Attach function — usually `apiClient.attachToBugReport.bind(api)`. */
188
+ attach: (bugReportId: string, attachment: BugReportAttachmentInput) => Promise<BugReportAttachmentResponse>;
189
+ /** Called per successful upload; useful for telemetry. */
190
+ onSuccess?: (entry: QueuedAttachmentEntry, response: BugReportAttachmentResponse) => void;
191
+ /** Called per permanent failure (4xx). */
192
+ onPermanentFailure?: (entry: QueuedAttachmentEntry, error: unknown) => void;
193
+ }
194
+ declare class SubmitQueue {
195
+ private readonly storage;
196
+ constructor(storage: TpkStorage);
197
+ enqueue(payload: BugReportPayload, options?: {
198
+ idempotencyKey?: string;
199
+ }): Promise<QueuedEntry>;
200
+ size(): Promise<number>;
201
+ /**
202
+ * Drain the queue, calling `submit()` per entry. Removes entries
203
+ * that succeed or hit a 4xx; leaves 5xx / network errors for the
204
+ * next call.
205
+ */
206
+ flush(options: QueueFlushOptions): Promise<QueueFlushResult>;
207
+ private read;
208
+ }
209
+ declare class AttachmentQueue {
210
+ private readonly storage;
211
+ constructor(storage: TpkStorage);
212
+ enqueue(bugReportId: string, attachment: BugReportAttachmentInput): Promise<QueuedAttachmentEntry>;
213
+ size(): Promise<number>;
214
+ /**
215
+ * Drain attachment uploads. Succeeds and 4xx failures are removed;
216
+ * 5xx / network-level failures stay queued for the next pass.
217
+ */
218
+ flush(options: AttachmentQueueFlushOptions): Promise<QueueFlushResult>;
219
+ private read;
220
+ }
221
+
222
+ /** How an annotated element completes its parent task. */
223
+ type CompletionTrigger = 'on-tap' | 'on-input' | 'on-visible' | 'on-navigation' | 'manual';
224
+ /** Annotation linking a UI element to a test task. */
225
+ interface TaskAnnotation {
226
+ /** Stable id for this annotation (typically a UUID). */
227
+ id: string;
228
+ /** Task this annotation is part of. */
229
+ taskId: string;
230
+ /** Optional focus area grouping multiple annotations. */
231
+ focusAreaId?: string;
232
+ /** Free-text labels for AI / semantic discovery. */
233
+ semanticLabels: string[];
234
+ /** What action on the element counts as task progress. */
235
+ completionTrigger: CompletionTrigger;
236
+ /** How many interactions before the task is considered complete. */
237
+ requiredInteractionCount: number;
238
+ /** Live counter — bumped via recordInteraction. */
239
+ currentInteractionCount: number;
240
+ /** Native widget kind hint ("Button", "TextInput"). */
241
+ elementType?: string;
242
+ /** Stable element identifier — usually a testID. */
243
+ elementKey?: string;
244
+ /** App version this annotation applies to (exact match for now). */
245
+ versionRange?: string;
246
+ /** Free-form extension bag. */
247
+ metadata: Record<string, unknown>;
248
+ createdAt: Date;
249
+ updatedAt: Date;
250
+ }
251
+ type AnnotationEventType = 'registered' | 'updated' | 'unregistered' | 'interaction' | 'completed';
252
+ interface AnnotationEvent {
253
+ type: AnnotationEventType;
254
+ annotation: TaskAnnotation;
255
+ /** Present on 'interaction' and 'completed' events. Carries the
256
+ * detail record produced by recordInteraction(...). Other event
257
+ * types leave this undefined. */
258
+ interaction?: AnnotationInteraction;
259
+ }
260
+ type AnnotationListener = (event: AnnotationEvent) => void;
261
+ /**
262
+ * Type of interaction that recordInteraction(...) is being told
263
+ * about. Mirrors the Flutter SDK's InteractionType enum 1:1.
264
+ */
265
+ type InteractionType = 'tap' | 'input' | 'scroll' | 'navigation' | 'visible' | 'long-press' | 'drag' | 'custom';
266
+ interface InteractionBounds {
267
+ x: number;
268
+ y: number;
269
+ width: number;
270
+ height: number;
271
+ }
272
+ /** Optional detail bag for recordInteraction(...). */
273
+ interface RecordInteractionDetails {
274
+ type?: InteractionType;
275
+ /** Pixel bounds of the element at the time of the interaction. */
276
+ elementBounds?: InteractionBounds;
277
+ /** Text typed by the user, if `type: 'input'`. */
278
+ inputValue?: string;
279
+ /** How long the interaction took (ms) — useful for `'long-press'`. */
280
+ durationMs?: number;
281
+ /** Free-form extension bag. */
282
+ metadata?: Record<string, unknown>;
283
+ }
284
+ /** A single interaction record, kept in the registry's history ring. */
285
+ interface AnnotationInteraction {
286
+ id: string;
287
+ sessionId: string;
288
+ annotationId: string;
289
+ taskId: string;
290
+ type: InteractionType;
291
+ timestamp: Date;
292
+ elementBounds?: InteractionBounds;
293
+ inputValue?: string;
294
+ durationMs?: number;
295
+ metadata: Record<string, unknown>;
296
+ /** True when this interaction was the one that pushed the
297
+ * annotation's currentInteractionCount over its required threshold. */
298
+ triggeredCompletion: boolean;
299
+ }
300
+ /** Aggregated stats over the interactions for one task. */
301
+ interface TaskInteractionSummary {
302
+ taskId: string;
303
+ totalInteractions: number;
304
+ interactionsByType: Partial<Record<InteractionType, number>>;
305
+ firstInteraction?: Date;
306
+ lastInteraction?: Date;
307
+ /** Sum of durationMs over interactions that reported one. */
308
+ totalTimeMs: number;
309
+ /** Was at least one of the recorded interactions a completion trigger? */
310
+ autoCompleted: boolean;
311
+ }
312
+ /** What you need to pass to register a new annotation. */
313
+ interface RegisterAnnotationInput {
314
+ id?: string;
315
+ taskId: string;
316
+ focusAreaId?: string;
317
+ semanticLabels?: string[];
318
+ completionTrigger?: CompletionTrigger;
319
+ requiredInteractionCount?: number;
320
+ elementType?: string;
321
+ elementKey?: string;
322
+ versionRange?: string;
323
+ metadata?: Record<string, unknown>;
324
+ /** React ref pointing at the actual rendered element. */
325
+ ref?: RefObject<unknown>;
326
+ }
327
+ /** Snapshot for export to the server / automation runner. */
328
+ interface AnnotatedElementInfo {
329
+ annotation: TaskAnnotation;
330
+ /** True while the React ref still resolves to a mounted node. */
331
+ isMounted: boolean;
332
+ /** Pull from elementType / metadata; reserved for future RN bounds. */
333
+ bounds?: {
334
+ x: number;
335
+ y: number;
336
+ width: number;
337
+ height: number;
338
+ };
339
+ }
340
+ /**
341
+ * Singleton registry. Use `TaskAnnotationRegistry.instance` or the
342
+ * exported `annotations` shortcut.
343
+ */
344
+ declare class TaskAnnotationRegistry {
345
+ private static _instance;
346
+ static get instance(): TaskAnnotationRegistry;
347
+ /** Reset for tests — never call from app code. */
348
+ static resetInstance(): void;
349
+ /** Bound for the interaction history ring. Older records are
350
+ * dropped when the buffer hits this. Tunable via setInteractionHistoryLimit. */
351
+ private static DEFAULT_INTERACTION_LIMIT;
352
+ private annotations;
353
+ private refs;
354
+ private byTask;
355
+ private byFocusArea;
356
+ private listeners;
357
+ /** Rolling interaction history. Bounded by interactionLimit. */
358
+ private interactions;
359
+ private interactionLimit;
360
+ /** Tester-session id stamped onto each interaction record. */
361
+ private sessionId;
362
+ /** Subscribe to register/update/unregister/interaction events. */
363
+ subscribe(listener: AnnotationListener): () => void;
364
+ /** Register a new annotation. Returns the assigned id. */
365
+ register(input: RegisterAnnotationInput): string;
366
+ /** Patch an existing annotation. Indices update if taskId / focus changes. */
367
+ update(id: string, patch: Partial<Omit<RegisterAnnotationInput, 'id'>>): void;
368
+ /** Remove an annotation + its indices. */
369
+ unregister(id: string): void;
370
+ /**
371
+ * Record one interaction with an annotated element.
372
+ *
373
+ * The optional `details` describe what kind of interaction it was
374
+ * (tap / input / scroll / …), the element bounds at the time, the
375
+ * input value for text fields, and a duration for gestures like
376
+ * long-press. A full `AnnotationInteraction` record is appended to
377
+ * the history ring and attached to the emitted event.
378
+ *
379
+ * Emits a `'completed'` event (and stamps `triggeredCompletion`
380
+ * on the interaction record) when `currentInteractionCount` hits
381
+ * the annotation's `requiredInteractionCount` threshold.
382
+ *
383
+ * Backwards-compatible: calling `recordInteraction(id)` without a
384
+ * second argument behaves like before — the recorded type defaults
385
+ * to `'custom'`.
386
+ */
387
+ recordInteraction(id: string, details?: RecordInteractionDetails): void;
388
+ /**
389
+ * Stamp every subsequent interaction record with this session id.
390
+ * Mirrors AnnotationInteractionTracker.setSessionId in the Flutter
391
+ * SDK. Typically wired to TpkExpo.sessionId on init.
392
+ */
393
+ setSessionId(sessionId: string): void;
394
+ /** Tune the interaction history ring size. 0 disables history. */
395
+ setInteractionHistoryLimit(limit: number): void;
396
+ /**
397
+ * Read the interaction history. Optionally narrow by taskId or
398
+ * annotationId. Returns a copy — mutating the result is safe.
399
+ */
400
+ getInteractions(filter?: {
401
+ taskId?: string;
402
+ annotationId?: string;
403
+ }): AnnotationInteraction[];
404
+ /**
405
+ * Aggregate stats for one task — total interactions, breakdown by
406
+ * type, first/last timestamps, accumulated durationMs, and whether
407
+ * the task was auto-completed by any recorded interaction.
408
+ */
409
+ getInteractionSummary(taskId: string): TaskInteractionSummary;
410
+ /** Drop the interaction history. Tests + privacy-on-logout. */
411
+ clearInteractions(): void;
412
+ private appendInteraction;
413
+ /** Get a single annotation by id. */
414
+ get(id: string): TaskAnnotation | undefined;
415
+ /** All annotations as a snapshot list. */
416
+ getAll(): TaskAnnotation[];
417
+ /** Annotations belonging to a specific task. */
418
+ getForTask(taskId: string): TaskAnnotation[];
419
+ /** Annotations belonging to a specific focus area. */
420
+ getForFocusArea(focusAreaId: string): TaskAnnotation[];
421
+ /** Find by semantic label (case-insensitive substring match). */
422
+ findByLabel(label: string): TaskAnnotation[];
423
+ /** Find by elementKey (typically a testID). */
424
+ findByKey(elementKey: string): TaskAnnotation | undefined;
425
+ /** Resolve the React ref for an annotation (if still mounted). */
426
+ getRef(id: string): RefObject<unknown> | undefined;
427
+ /**
428
+ * Snapshot for automation: every annotation + whether its ref still
429
+ * resolves. Bounds field is reserved for a later RN measureInWindow
430
+ * pass; left undefined here so the JSON stays small.
431
+ */
432
+ snapshot(filter?: {
433
+ taskId?: string;
434
+ focusAreaId?: string;
435
+ }): AnnotatedElementInfo[];
436
+ /** Stats useful for debugging / a future devtools panel. */
437
+ getStatistics(): {
438
+ totalAnnotations: number;
439
+ annotationsByTask: Record<string, number>;
440
+ annotationsByFocusArea: Record<string, number>;
441
+ uniqueTasks: number;
442
+ uniqueFocusAreas: number;
443
+ };
444
+ /** Wipe everything (tests only). */
445
+ clear(): void;
446
+ private idsFromIndex;
447
+ private emit;
448
+ }
449
+ /** Convenience shortcut. Equivalent to `TaskAnnotationRegistry.instance`. */
450
+ declare const annotations: TaskAnnotationRegistry;
451
+
452
+ interface TaskProgress {
453
+ completed: number;
454
+ total: number;
455
+ hasTasks: boolean;
456
+ allDone: boolean;
457
+ }
458
+ /** Derive {completed, total} from a task-list response. Prefers the server
459
+ * `summary.completed`; falls back to counting completed tasks. */
460
+ declare function deriveTaskProgress(res: TaskListResponse): TaskProgress;
461
+ /**
462
+ * Find the assigned task whose preset id or assignment id matches `key` (the
463
+ * semantic annotation taskId). Mirrors Flutter's _findAssignment: a host can
464
+ * annotate a widget with either the task-preset id or the assignment id.
465
+ */
466
+ declare function findAssignmentForTask(tasks: TesterTask[], key: string): TesterTask | null;
467
+
468
+ interface TpkExpoConfig {
469
+ /** Project UUID — bootstrap via `tpk project create` first. */
470
+ projectId: string;
471
+ /** Stable per-install code used as the anonymous tester id. */
472
+ testerCode: string;
473
+ /**
474
+ * API base URL. Defaults to https://api.testerpaykit.com.
475
+ * Point at a local Mac (http://192.168.x.x:18080) during dev.
476
+ */
477
+ apiBaseUrl?: string;
478
+ /** API key (optional — server allows anonymous-tester JWTs). */
479
+ apiKey?: string;
480
+ /**
481
+ * Enable global crash capture. Defaults to true. Caught crashes
482
+ * are submitted as `type: 'crash'` bug reports automatically.
483
+ */
484
+ captureCrashes?: boolean;
485
+ /**
486
+ * How many breadcrumbs to keep in the ring buffer (default 50).
487
+ * Older breadcrumbs are dropped as new ones come in.
488
+ */
489
+ maxBreadcrumbs?: number;
490
+ /**
491
+ * Automatically flush the offline retry queue on init.
492
+ * Defaults to true. Set false if you want to control the timing.
493
+ */
494
+ flushQueueOnInit?: boolean;
495
+ /**
496
+ * Patch global.fetch to record HTTP requests as breadcrumbs.
497
+ * Default true. URLs matching api.testerpaykit.com / :18080 are
498
+ * ignored automatically (no feedback loops on TPK's own calls).
499
+ */
500
+ captureNetwork?: boolean;
501
+ /**
502
+ * Durable session sync: flush buffered telemetry + retry the offline
503
+ * upload queue every N ms AND when the app goes to background. Default
504
+ * 60000 (60s). Mirrors the Flutter SDK's lifecycle + periodic flush so a
505
+ * backgrounded/killed app or a long session doesn't lose telemetry.
506
+ */
507
+ flushIntervalMs?: number;
508
+ /**
509
+ * Override persistence. Defaults to AsyncStorage via ExpoStorage.
510
+ * Use this to plug in MMKV/SQLite-backed storage for larger queues.
511
+ */
512
+ storage?: TpkStorage;
513
+ }
514
+ interface SubmitBugInput {
515
+ title: string;
516
+ description: string;
517
+ type?: BugReportType;
518
+ severity?: BugSeverity;
519
+ category?: BugCategory;
520
+ currentScreen?: string;
521
+ reproductionSteps?: string[];
522
+ expectedBehavior?: string;
523
+ actualBehavior?: string;
524
+ /**
525
+ * Voice-bug split (A2): raw O-Ton transcript + spoken language.
526
+ * When `transcript` is set the server treats title/description as
527
+ * the tester's approved O-Ton, stores them verbatim, and derives
528
+ * the English enriched canonical fields. Absent for typed reports.
529
+ */
530
+ transcript?: string;
531
+ sourceLanguage?: string;
532
+ }
533
+ interface EndSessionInput {
534
+ reason?: TesterSessionEndReason;
535
+ bugsFound?: number;
536
+ tasksCompleted?: number;
537
+ foregroundSeconds?: number;
538
+ }
539
+ interface FlushTelemetryResult {
540
+ eventsInserted: number;
541
+ breadcrumbsInserted: number;
542
+ }
543
+ /**
544
+ * Where a `submitBug` call landed. Lets the host UI render honest
545
+ * feedback after the call (the bug we shipped on 2026-05-28 was a
546
+ * green ✓ even when the report was actually queued offline).
547
+ *
548
+ * - `uploaded` Server accepted, fresh row created.
549
+ * - `deduplicated` Server matched an existing row via
550
+ * X-Idempotency-Key → the SDK's retry won the
551
+ * race. Treat as success.
552
+ * - `queued` Saved offline, will retry on next flush.
553
+ * - `failedPermanent` Server returned 4xx — payload is rejected,
554
+ * won't retry.
555
+ */
556
+ type SubmitBugOutcome = 'uploaded' | 'deduplicated' | 'queued' | 'failedPermanent';
557
+ /**
558
+ * Result of [TpkExpo.submitBug]. Drives the host UI message —
559
+ * see [SubmitBugOutcome] for the exact mapping.
560
+ */
561
+ interface SubmitBugResult {
562
+ outcome: SubmitBugOutcome;
563
+ /** Server-side bug-report id once we have one. */
564
+ serverId?: string;
565
+ /** Idempotency key the SDK used / persisted with the queue entry. */
566
+ idempotencyKey: string;
567
+ /** Number of bug-reports still waiting in the offline queue. */
568
+ pendingCount: number;
569
+ }
570
+ /**
571
+ * Initialise the TesterPayKit client for an Expo app.
572
+ *
573
+ * const tpk = await TpkExpo.init({
574
+ * projectId: '<uuid>',
575
+ * testerCode: deviceCodeFromSettingsScreen,
576
+ * apiBaseUrl: __DEV__ ? 'http://192.168.178.69:18080' : undefined,
577
+ * });
578
+ * await tpk.submitBug({ title: 'X broke', description: '...' });
579
+ * tpk.trackScreenView('home');
580
+ * tpk.trackTap('home', 'sign_up_button');
581
+ */
582
+ declare class TpkExpo {
583
+ private readonly config;
584
+ readonly api: TesterPayKitApiClient;
585
+ private readonly storage;
586
+ readonly breadcrumbs: Breadcrumbs;
587
+ private readonly queue;
588
+ private readonly attachmentQueue;
589
+ private readonly crashQueue;
590
+ private uninstallCrashHandler;
591
+ private uninstallNetworkCapture;
592
+ /** @internal — set by constructor, exposed via [ready] getter. */
593
+ private readonly _ready;
594
+ /**
595
+ * Resolves when both the anonymous token AND the server session
596
+ * are ready. Host apps can `await tpk.ready` before firing
597
+ * authenticated calls, but it's OPTIONAL — the queue drains
598
+ * automatically once the token arrives.
599
+ */
600
+ get ready(): Promise<void>;
601
+ /**
602
+ * Singleton task-annotation registry. Exposed so consumers can
603
+ * subscribe to events or read snapshots without importing the
604
+ * `annotations` module separately:
605
+ *
606
+ * tpk.annotations.subscribe(event => log(event));
607
+ * tpk.annotations.snapshot({ taskId: 'task-1' });
608
+ */
609
+ readonly annotations: TaskAnnotationRegistry;
610
+ private readonly sessionEvents;
611
+ private uninstallDurableSync;
612
+ private uninstallTaskBinding;
613
+ private constructor();
614
+ /** Active server session id. Updated by init or rotate. Used to route telemetry. */
615
+ sessionId: string;
616
+ /** Active tester identity. Updated by background auth flow. */
617
+ tester: AnonymousLoginResponse['tester'];
618
+ static init(config: TpkExpoConfig): Promise<TpkExpo>;
619
+ /**
620
+ * POST a bug report to the server. Device + app snapshots are
621
+ * gathered automatically; recent breadcrumbs are attached. On
622
+ * network failure the report is queued and retried on next init.
623
+ *
624
+ * Returns a [SubmitBugResult] so the host UI can render honest
625
+ * feedback — the bug we shipped on 2026-05-28 was a green ✓ even
626
+ * when the report was actually queued offline. Now the caller can
627
+ * branch on `result.outcome` and show the right message.
628
+ *
629
+ * The same UUIDv4 [SubmitBugResult.idempotencyKey] is sent as the
630
+ * `X-Idempotency-Key` header on the initial POST AND every queue
631
+ * retry, so the server can dedup across attempts (migration 027).
632
+ */
633
+ submitBug(input: SubmitBugInput): Promise<SubmitBugResult>;
634
+ /** Track a screen-view breadcrumb. */
635
+ trackScreenView(screen: string, data?: Record<string, unknown>): void;
636
+ /** Track a tap breadcrumb. */
637
+ trackTap(screen: string, target: string, data?: Record<string, unknown>): void;
638
+ /** Track a custom event breadcrumb. */
639
+ trackEvent(target: string, data?: Record<string, unknown>): void;
640
+ /**
641
+ * Read-side mirror of Flutter's EventTracker.getEventCounts —
642
+ * tallies the in-memory `sessionEvents` buffer by eventType.
643
+ * After `flushTelemetry()` the buffer is empty.
644
+ */
645
+ getEventCounts(filter?: PeriodFilter): Record<string, number>;
646
+ /** Distinct `screenRoute` values seen since the last flush. */
647
+ getUniqueScreens(filter?: PeriodFilter): string[];
648
+ /**
649
+ * Snapshot session stats over the in-memory buffer — screen views,
650
+ * taps, custom events, unique screens, in-buffer duration. Empty
651
+ * after a flush.
652
+ */
653
+ getSessionStats(filter?: PeriodFilter): SessionStatsSnapshot;
654
+ /**
655
+ * Activity-gated paid minutes for the current session — paid time is
656
+ * capped by actual interaction so an idle / wake-tapped session earns
657
+ * ~nothing while real testing earns the full duration. Mirrors
658
+ * testerpaykit_core PayoutCalculator.engagedMinutes (parity with the
659
+ * Flutter SDK's activity-gated earnings). Drive an honest in-app
660
+ * earnings estimate from this instead of raw foreground time.
661
+ */
662
+ getEngagedMinutes(filter?: PeriodFilter): number;
663
+ /**
664
+ * Bug reports this tester submitted (newest first) with their current
665
+ * status — powers the "Meine Bugs" screen. Throws on network/auth error so
666
+ * the screen can render the failure. Mirrors Flutter's getMyBugReports.
667
+ */
668
+ getMyBugs(params?: {
669
+ status?: string;
670
+ limit?: number;
671
+ }): Promise<MyBugReportSummary[]>;
672
+ /**
673
+ * This tester's in-app notifications (newest first) + the unread count —
674
+ * powers the "Nachrichten" inbox. Mirrors the Flutter SDK.
675
+ */
676
+ getNotifications(params?: {
677
+ limit?: number;
678
+ unreadOnly?: boolean;
679
+ }): Promise<NotificationsResult>;
680
+ /**
681
+ * Mark notifications read — one by `id`, or all when omitted. Returns the
682
+ * new unread count.
683
+ */
684
+ markNotificationsRead(params?: {
685
+ id?: string;
686
+ }): Promise<number>;
687
+ /**
688
+ * Onboard with a runtime invite code (instead of the baked-in
689
+ * config.testerCode): authenticate anonymously with `code`, persist the
690
+ * auth + a fresh session, and update the in-memory identity. Powers the
691
+ * InviteCodeScreen. Mirrors the Flutter SDK's loginAnonymous(code). Throws
692
+ * on auth failure so the screen can surface it.
693
+ */
694
+ loginWithInviteCode(code: string): Promise<void>;
695
+ /**
696
+ * Tester checklist progress — {completed, total, hasTasks, allDone} for the
697
+ * "X von Y erledigt" display. Mirrors the Flutter SDK.
698
+ */
699
+ getTaskProgress(): Promise<TaskProgress>;
700
+ /**
701
+ * Report a task assignment complete (start → complete; the server only
702
+ * completes an in-progress task).
703
+ */
704
+ completeTask(assignmentId: string): Promise<void>;
705
+ /**
706
+ * Auto-complete assigned tasks when their annotated widget reports a
707
+ * 'completed' interaction. Maps the semantic annotation taskId to an
708
+ * assignment and reports it. Returns an unsubscribe. Mirrors Flutter's
709
+ * TaskProgressService.bindTracker — wired in init, torn down in dispose.
710
+ */
711
+ bindTaskCompletion(): () => void;
712
+ private autoCompleteTask;
713
+ /** Flush the offline retry queue immediately. */
714
+ flushQueue(): Promise<QueueFlushResult>;
715
+ /**
716
+ * Attach a file to a submitted bug report. Transient failures are
717
+ * queued and retried via flushAttachmentQueue(); 4xx failures throw.
718
+ */
719
+ attachToBugReport(bugReportId: string, attachment: BugReportAttachmentInput): Promise<BugReportAttachmentResponse | null>;
720
+ /** Flush queued attachment uploads immediately. */
721
+ flushAttachmentQueue(): Promise<QueueFlushResult>;
722
+ /** Cached crashes available for post-crash review or retry. */
723
+ getPendingCrashes(): Promise<CachedCrash[]>;
724
+ /** Drop one cached crash after the app has reviewed/dismissed it. */
725
+ discardCachedCrash(id: string): Promise<void>;
726
+ /**
727
+ * Try uploading cached crashes. Failed uploads remain cached so a
728
+ * future launch can surface them for review or retry.
729
+ */
730
+ flushCachedCrashes(): Promise<number>;
731
+ /** Flush pending session events + breadcrumbs to timeline endpoints. */
732
+ flushTelemetry(): Promise<FlushTelemetryResult>;
733
+ /** End the active server-side tester session. */
734
+ endSession(input?: EndSessionInput): Promise<void>;
735
+ /** Rotate the server-side session id (call after a logical restart). */
736
+ rotateSession(): Promise<void>;
737
+ /** Drop the cached anon-tester JWT — next init() re-acquires one. */
738
+ forgetAuth(): Promise<void>;
739
+ /**
740
+ * List the project's knowledge-base files — markdown docs the
741
+ * coordinator uploaded that feed the widget's "double-tap → ask a
742
+ * question about the project" voice flow. Returns metadata only;
743
+ * call `getKnowledgeFile` for the markdown body.
744
+ *
745
+ * Defaults to scoping by the project id the SDK was initialised
746
+ * with — pass an explicit bundle id / UUID to override.
747
+ */
748
+ listKnowledgeFiles(bundleIdOrProjectId?: string): Promise<{
749
+ projectId: string;
750
+ files: _testerpaykit_api_client.KnowledgeFileSummary[];
751
+ }>;
752
+ /**
753
+ * Fetch one knowledge-base file with its full markdown content.
754
+ * Pair with `listKnowledgeFiles` to discover ids.
755
+ */
756
+ getKnowledgeFile(fileId: string, bundleIdOrProjectId?: string): Promise<_testerpaykit_api_client.KnowledgeFile>;
757
+ /**
758
+ * Ask a natural-language question about the project. Server embeds
759
+ * the question, retrieves top-K relevant chunks from the project's
760
+ * knowledge-base, and asks gpt-4o-mini to synthesise an answer
761
+ * citing those chunks. Used by the SDK widget's "double-tap →
762
+ * speak → answer" voice flow.
763
+ *
764
+ * Defaults to scoping by the project id the SDK was initialised
765
+ * with; pass an explicit bundle id / UUID to override.
766
+ */
767
+ askKnowledgeBase(question: string, bundleIdOrProjectId?: string): Promise<_testerpaykit_api_client.KnowledgeBaseAnswer>;
768
+ /**
769
+ * Best-effort durable flush: push buffered telemetry to the session
770
+ * timeline and retry any queued bug uploads. Never throws — it's called
771
+ * from the periodic timer and the AppState background handler (the last
772
+ * chance before the OS may kill a backgrounded app). Mirrors the Flutter
773
+ * SDK's lifecycle + periodic flush.
774
+ */
775
+ private flushDurable;
776
+ /** Tear down crash handler + network interceptor + durable sync (test hygiene). */
777
+ dispose(): void;
778
+ /** Build a bug-report payload — exposed so tests can introspect. */
779
+ buildPayload(input: SubmitBugInput): Promise<BugReportPayload>;
780
+ /** Persist crash context before attempting a best-effort upload. */
781
+ private captureCrash;
782
+ /** Auto-built crash submit — called from the cached crash flusher. */
783
+ private submitCrashReport;
784
+ }
785
+
786
+ declare const INTERACTION_NAV_WEIGHT = 3;
787
+ declare const MIN_INTERACTIONS_PER_ACTIVE_MINUTE = 4;
788
+ interface EngagedMinutesInput {
789
+ durationMinutes: number;
790
+ taps: number;
791
+ screenViews: number;
792
+ }
793
+ /**
794
+ * Engaged (paid) minutes — the activity-gated replacement for raw
795
+ * foreground/wall-clock duration. Never exceeds `durationMinutes`; returns
796
+ * 0 for zero/negative duration or zero interaction.
797
+ *
798
+ * Mirrors `PayoutCalculator.engagedMinutes` in testerpaykit_core.
799
+ */
800
+ declare function engagedMinutes(input: EngagedMinutesInput): number;
801
+
802
+ interface UseShakeOptions {
803
+ /** Acceleration delta threshold above which a shake is counted. */
804
+ threshold?: number;
805
+ /** Minimum interval between consecutive callbacks, ms. */
806
+ cooldownMs?: number;
807
+ /** Skip listening if false (lets you gate by user preference). */
808
+ enabled?: boolean;
809
+ }
810
+ /**
811
+ * Fire `onShake()` when the device is shaken. Wraps expo-sensors'
812
+ * Accelerometer with a delta-magnitude threshold + cooldown.
813
+ *
814
+ * Usage:
815
+ * useShake({ onShake: () => openBugReport(), enabled: !modalOpen });
816
+ *
817
+ * Returns nothing — subscription is cleaned up on unmount.
818
+ */
819
+ declare function useShake({ onShake, threshold, cooldownMs, enabled, }: UseShakeOptions & {
820
+ onShake: () => void;
821
+ }): void;
822
+
823
+ interface TesterPayKitContextValue {
824
+ client: TpkExpo | null;
825
+ ready: boolean;
826
+ loading: boolean;
827
+ error: Error | null;
828
+ }
829
+ interface TesterPayKitProviderProps {
830
+ children: React.ReactNode;
831
+ /**
832
+ * Pass an already initialized client when the app owns lifecycle.
833
+ * If omitted, provide `config` and the provider initializes it.
834
+ */
835
+ client?: TpkExpo | null;
836
+ config?: TpkExpoConfig;
837
+ onReady?: (client: TpkExpo) => void;
838
+ onError?: (error: Error) => void;
839
+ }
840
+ declare function TesterPayKitProvider({ children, client, config, onReady, onError, }: TesterPayKitProviderProps): React.ReactElement;
841
+ declare function useTesterPayKit(): TesterPayKitContextValue;
842
+
843
+ declare const ONBOARDING_DONE_STORAGE_KEY = "onboarding-done";
844
+ declare const SCREENSHOT_CONSENT_STORAGE_KEY = "screenshot-consent";
845
+ interface OnboardingStorage {
846
+ get<T = unknown>(key: string): Promise<T | null>;
847
+ set(key: string, value: unknown): Promise<void>;
848
+ remove(key: string): Promise<void>;
849
+ }
850
+ /** Has the user completed (or skipped) onboarding on this device? */
851
+ declare function hasCompletedOnboarding(storage: OnboardingStorage): Promise<boolean>;
852
+ declare function markOnboardingComplete(storage: OnboardingStorage, options?: {
853
+ screenshotConsent?: boolean;
854
+ }): Promise<void>;
855
+ /** Read the persisted screenshot-consent flag. Defaults to false. */
856
+ declare function hasScreenshotConsent(storage: OnboardingStorage): Promise<boolean>;
857
+ /** Wipe both flags. Useful on logout / forgetAuth. */
858
+ declare function resetOnboardingState(storage: OnboardingStorage): Promise<void>;
859
+
860
+ interface FloatingFeedbackButtonProps {
861
+ /** Tap "Report Bug". Required — this is the primary action. */
862
+ onReportBug: () => void;
863
+ /** Tap "Feedback". Required — general (non-bug) tester feedback. */
864
+ onGeneralFeedback: () => void;
865
+ /** Tap "My Workboard" — opens the TesterDashboard. */
866
+ onViewDashboard: () => void;
867
+ /** Tap "End Session" — typically opens SessionEndDialog. */
868
+ onEndSession: () => void;
869
+ /** Tap "My Retests". When omitted, the row is hidden. */
870
+ onShowRetests?: () => void;
871
+ /** Badge next to "My Retests". */
872
+ retestCount?: number;
873
+ /** Tap "Debug Logs" — typically opens a TpkTalker history viewer. */
874
+ onShowDebugLogs?: () => void;
875
+ /** Tap "My Bugs" — opens the MyBugsSheet (this tester's submitted bugs +
876
+ * current status). When omitted, the row is hidden. */
877
+ onShowMyBugs?: () => void;
878
+ /** Tap "Session Details" — opens the SessionDetailsSheet (taps, screens,
879
+ * active vs paid minutes, expected earnings). When omitted, hidden. */
880
+ onShowSessionDetails?: () => void;
881
+ /** Tap "Nachrichten" — opens the NotificationsSheet (server-pull inbox).
882
+ * When omitted, the row is hidden. */
883
+ onShowMessages?: () => void;
884
+ /** Unread-notification count shown next to "Nachrichten" (distinct from
885
+ * `notificationCount`, which is the cached-crash count). */
886
+ unreadMessageCount?: number;
887
+ /** Tap "🤖 Auto Test (AI)" — opens the AI-tester surface that lets
888
+ * a server-side LLM drive the app for the next N actions. When
889
+ * omitted, the row is hidden. See `AiRemoteControl` for the
890
+ * receiver-side wiring. */
891
+ onAutoTest?: () => void;
892
+ /** Long-press the FAB — opens the Voice-AI bug-narration flow.
893
+ * When omitted, long-press is a no-op. */
894
+ onLongPressVoiceBug?: () => void | Promise<void>;
895
+ /** Action behind "Send N cached crashes". Returns the count
896
+ * actually submitted. Row is hidden when omitted OR when
897
+ * notificationCount is 0. */
898
+ onFlushCachedCrashes?: () => Promise<number> | number;
899
+ /** Notification badge value (top-right of the FAB) + the
900
+ * "Send N cached crashes" row count. */
901
+ notificationCount?: number;
902
+ /** Initial position. Default (16, 100). The user can drag it. */
903
+ position?: {
904
+ x: number;
905
+ y: number;
906
+ };
907
+ /** When the active server session started — drives the earnings
908
+ * clock. Null hides the clock. */
909
+ sessionStartedAt?: Date | null;
910
+ /** Base reward per session. Default 1.00. */
911
+ earningsBaseAmount?: number;
912
+ /** Per-minute rate added on top of the base. Default 0.10. */
913
+ earningsPerMinuteRate?: number;
914
+ /** ISO-4217 currency code. Default 'EUR' (DACH-first). */
915
+ earningsCurrency?: string;
916
+ /** Outer style override. */
917
+ style?: StyleProp<ViewStyle>;
918
+ testID?: string;
919
+ /** Show the one-time, first-tap onboarding tour. Default true.
920
+ * Set false to disable the tour entirely (e.g. in tests / demos). */
921
+ enableFirstTapTour?: boolean;
922
+ /** Storage adapter for the tour's "seen" flag. Optional — when
923
+ * omitted, the FAB provides a sensible default (AsyncStorage on
924
+ * native, window.localStorage on web) so the widget needs zero host
925
+ * wiring. A failed/absent storage degrades gracefully. */
926
+ tourStorage?: OnboardingStorage;
927
+ }
928
+ declare function FloatingFeedbackButton({ onReportBug, onGeneralFeedback, onViewDashboard, onEndSession, onShowRetests, retestCount, onShowDebugLogs, onShowMyBugs, onShowSessionDetails, onShowMessages, unreadMessageCount, onAutoTest, onLongPressVoiceBug, onFlushCachedCrashes, notificationCount, position, sessionStartedAt, earningsBaseAmount, earningsPerMinuteRate, earningsCurrency, style, testID, enableFirstTapTour, tourStorage, }: FloatingFeedbackButtonProps): React.ReactElement;
929
+
930
+ type AttachmentKind = 'screenshot' | 'image' | 'video' | 'audio' | 'screen-recording' | 'log' | 'json' | 'other';
931
+ interface BugReportAttachmentDraft {
932
+ /** Stable client-side id — separate from the server-side id. */
933
+ id: string;
934
+ kind: AttachmentKind;
935
+ /** Display label. */
936
+ name: string;
937
+ /** Base64 (raw, no data-URI prefix). The server endpoint accepts
938
+ * exactly this shape — see api-client.attachToBugReport. */
939
+ base64: string;
940
+ /** Mime-type for the upload. */
941
+ mimeType: string;
942
+ /** Approx byte size — populated where the source knows it. */
943
+ byteLength?: number;
944
+ }
945
+ type BugFrequency = 'always' | 'often' | 'sometimes' | 'once';
946
+ interface BugReportDraft {
947
+ title: string;
948
+ description: string;
949
+ type: BugReportType;
950
+ severity: BugSeverity;
951
+ category: BugCategory;
952
+ currentScreen?: string;
953
+ reproductionSteps: string[];
954
+ expectedBehavior: string;
955
+ actualBehavior: string;
956
+ frequency?: BugFrequency;
957
+ affectedComponent?: string;
958
+ attachments: BugReportAttachmentDraft[];
959
+ /**
960
+ * Voice-bug split (A2): when set, this draft is voice-originated.
961
+ * The title/description the tester reviews are their O-Ton (own
962
+ * language); these ride to submit so the server stores the author
963
+ * view + derives the English enriched canonical fields. Undefined
964
+ * for typed reports.
965
+ */
966
+ transcript?: string;
967
+ sourceLanguage?: string;
968
+ }
969
+ interface CreateBugReportDraftInput {
970
+ title?: string;
971
+ description?: string;
972
+ type?: BugReportType;
973
+ severity?: BugSeverity;
974
+ category?: BugCategory;
975
+ currentScreen?: string;
976
+ /** Comma-or-newline-separated string OR ordered list. */
977
+ reproductionStepsText?: string;
978
+ reproductionSteps?: string[];
979
+ expectedBehavior?: string;
980
+ actualBehavior?: string;
981
+ }
982
+ interface BugReportSheetProps {
983
+ visible: boolean;
984
+ tpk?: Pick<TpkExpo, 'submitBug' | 'attachToBugReport'> | null;
985
+ /** What screen the user was on when they opened the dialog. */
986
+ currentScreen?: string;
987
+ /** Optional ref to the host's root view — used for the Screenshot
988
+ * Capture button. When omitted, screenshot capture stays disabled. */
989
+ captureRootRef?: RefObject<unknown>;
990
+ /** Auto-capture a screenshot the moment the sheet opens. Mirrors
991
+ * the Flutter SDK's behaviour: the tester opens the bug-report
992
+ * via the FAB and the screen they were just looking at is
993
+ * already attached. Default true when `captureRootRef` is
994
+ * provided. Pass `false` explicitly to suppress (e.g. if the
995
+ * host wants to control timing). */
996
+ autoCaptureOnOpen?: boolean;
997
+ /** Fires the voice-bug-input flow (Phase E-5). When omitted, the
998
+ * mic button in the header is hidden. */
999
+ onOpenVoiceBug?: () => void | Promise<void>;
1000
+ onClose: () => void;
1001
+ /**
1002
+ * Fires after [submitBugReportDraft] returns. Receives the
1003
+ * [SubmitBugResult] so the host can show honest UI per-outcome
1004
+ * (queued / uploaded / deduplicated / failedPermanent) — fixes the
1005
+ * 2026-05-28 "green ✓ on offline" bug.
1006
+ */
1007
+ onSubmitted?: (result: SubmitBugResult) => void;
1008
+ onError?: (error: Error) => void;
1009
+ defaultSeverity?: BugSeverity;
1010
+ /** Optional pre-fill — fields not in the patch fall back to the
1011
+ * factory defaults. Typically used to seed the sheet from the
1012
+ * VoiceBugInputSheet extraction (title / description / expected
1013
+ * / actual / frequency / category). */
1014
+ initialDraft?: Partial<BugReportDraft>;
1015
+ /** Max attachments + total size, mirrors Flutter's safeguards. */
1016
+ maxAttachments?: number;
1017
+ maxTotalSizeMB?: number;
1018
+ style?: StyleProp<ViewStyle>;
1019
+ }
1020
+ declare function createBugReportDraft(input?: CreateBugReportDraftInput): BugReportDraft;
1021
+ declare function canSubmitBugReportDraft(draft: BugReportDraft): boolean;
1022
+ declare function submitBugReportDraft(tpk: Pick<TpkExpo, 'submitBug' | 'attachToBugReport'>, draft: BugReportDraft): Promise<SubmitBugResult>;
1023
+ declare function BugReportSheet({ visible, tpk, currentScreen, captureRootRef, autoCaptureOnOpen, onOpenVoiceBug, onClose, onSubmitted, onError, defaultSeverity, initialDraft: initialDraftPatch, maxAttachments, maxTotalSizeMB, style, }: BugReportSheetProps): React.ReactElement;
1024
+
1025
+ interface DeviceSnapshot {
1026
+ platform: 'ios' | 'android' | 'web' | 'macos' | 'windows';
1027
+ osVersion?: string;
1028
+ model?: string;
1029
+ manufacturer?: string;
1030
+ isPhysicalDevice?: boolean;
1031
+ locale?: string;
1032
+ }
1033
+ interface AppSnapshot {
1034
+ version?: string;
1035
+ buildNumber?: string;
1036
+ bundleId?: string;
1037
+ buildMode: 'debug' | 'profile' | 'release';
1038
+ /**
1039
+ * Screen path that led to the bug — chronological, consecutive-deduped,
1040
+ * newest last (the final entry is the screen the bug happened on).
1041
+ * Mirrors the Flutter SDK's appSnapshot.navigationPath; the server +
1042
+ * `tpk bug context` surface it as the navigation flow.
1043
+ */
1044
+ navigationPath?: string[];
1045
+ }
1046
+ /**
1047
+ * Best-effort snapshot of the device. Uses expo-device when
1048
+ * available; falls back to react-native's Platform.
1049
+ */
1050
+ declare function getDeviceSnapshot(): Promise<DeviceSnapshot>;
1051
+ /**
1052
+ * Best-effort snapshot of the host app. Uses expo-application when
1053
+ * available; falls back to a build-mode-only object.
1054
+ */
1055
+ declare function getAppSnapshot(buildMode?: AppSnapshot['buildMode']): Promise<AppSnapshot>;
1056
+
1057
+ interface InstallNetworkCaptureOptions {
1058
+ breadcrumbs: Breadcrumbs;
1059
+ /**
1060
+ * URL patterns to IGNORE (don't record). Useful to avoid feedback
1061
+ * loops on TPK's own API + on metrics-collector services.
1062
+ * Default skips api.testerpaykit.com plus the local dev port.
1063
+ */
1064
+ ignorePatterns?: RegExp[];
1065
+ /**
1066
+ * When true, also record the response body's length (not the body
1067
+ * itself). Default true.
1068
+ */
1069
+ recordSizes?: boolean;
1070
+ }
1071
+ declare function installNetworkCapture(options: InstallNetworkCaptureOptions): () => void;
1072
+
1073
+ interface CaptureViewOptions {
1074
+ /** Image format. PNG default; JPG smaller but lossy. */
1075
+ format?: 'png' | 'jpg';
1076
+ /** 0–1 quality, JPG only. */
1077
+ quality?: number;
1078
+ /** Override result format (base64 default — what the server wants). */
1079
+ result?: 'base64' | 'tmpfile' | 'data-uri';
1080
+ /**
1081
+ * Redact regions wrapped in `<TpkSensitive>` before the bitmap is
1082
+ * grabbed. Default `true` — the SDK errs on the safe side; pass
1083
+ * `false` only if you have a reason (debugging, internal-only
1084
+ * captures) and know the screen contains no PII.
1085
+ */
1086
+ redactSensitive?: boolean;
1087
+ }
1088
+ interface ScreenshotResult {
1089
+ /** Base64-encoded image bytes (no data-URI prefix). */
1090
+ base64: string;
1091
+ /** Approximate byte size of the decoded image. */
1092
+ byteLength: number;
1093
+ /** Mime-type of the encoded image. */
1094
+ mimeType: 'image/png' | 'image/jpeg';
1095
+ }
1096
+ /**
1097
+ * Capture the contents of a React Native view as a base64 PNG/JPG.
1098
+ * Pass any ref returned by useRef() on a View; the parent component
1099
+ * doesn't need a special wrapper.
1100
+ *
1101
+ * Returns null if react-native-view-shot is not installed (peer-
1102
+ * optional). Throws if capture fails for a different reason.
1103
+ */
1104
+ declare function captureView(viewRef: RefObject<unknown>, options?: CaptureViewOptions): Promise<ScreenshotResult | null>;
1105
+ /**
1106
+ * Upload a captured screenshot as an attachment to an already-
1107
+ * submitted bug report. Returns the server's metadata response.
1108
+ */
1109
+ declare function uploadScreenshotAttachment(api: TesterPayKitApiClient, bugReportId: string, screenshot: ScreenshotResult, fileName?: string): Promise<BugReportAttachmentResponse>;
1110
+
1111
+ type SensitiveMaskingMode = 'blur' | 'pixelate' | 'hide';
1112
+ /**
1113
+ * Apply redaction CSS for every `data-tpk-sensitive` element on the
1114
+ * page. Idempotent — safe to call multiple times. Returns a teardown
1115
+ * function the caller is expected to invoke after capture.
1116
+ *
1117
+ * On non-web platforms this is a no-op + returns a no-op teardown.
1118
+ */
1119
+ declare function applySensitiveRedaction(): () => void;
1120
+
1121
+ /** Subscribe to capture-mode changes. Returns an unsubscribe fn.
1122
+ * Intended for use with `useSyncExternalStore`. */
1123
+ declare function subscribeNativeCaptureMode(listener: () => void): () => void;
1124
+ /** Read the current capture-mode flag. Stable snapshot for
1125
+ * useSyncExternalStore — returns the same primitive while the
1126
+ * flag hasn't changed. */
1127
+ declare function getNativeCaptureMode(): boolean;
1128
+ /** Flip capture mode on. Idempotent — re-calling while active is
1129
+ * a no-op (no listeners notified). */
1130
+ declare function beginNativeCapture(): void;
1131
+ /** Flip capture mode off. Idempotent — re-calling while inactive
1132
+ * is a no-op. */
1133
+ declare function endNativeCapture(): void;
1134
+ /**
1135
+ * Run `fn` with capture mode flipped on, then turn it off again
1136
+ * regardless of whether `fn` resolved or threw. Use this from
1137
+ * `captureView()` so the off-flag always fires.
1138
+ */
1139
+ declare function withNativeCapture<T>(fn: () => Promise<T>): Promise<T>;
1140
+
1141
+ interface TpkSensitiveProps {
1142
+ children: React.ReactNode;
1143
+ /** How to mask during capture. Default 'blur'. */
1144
+ mode?: SensitiveMaskingMode;
1145
+ /** Optional style passthrough — works the same as `View`. */
1146
+ style?: StyleProp<ViewStyle>;
1147
+ /** Set to false to opt out without removing the wrapper. */
1148
+ enabled?: boolean;
1149
+ /** Custom test id; default 'tpk-sensitive'. */
1150
+ testID?: string;
1151
+ }
1152
+ /**
1153
+ * Marks the wrapped children as sensitive. Screenshot capture
1154
+ * machinery redacts the region. Renders the children otherwise
1155
+ * unchanged.
1156
+ *
1157
+ * Behaviour by platform:
1158
+ * * Web: tags the underlying DOM element with `data-tpk-sensitive`
1159
+ * plus the chosen mode. `captureView` applies a CSS overlay
1160
+ * before grabbing the bitmap, then tears it down.
1161
+ * * Native (iOS/Android): renders the same View. There is no
1162
+ * equivalent capture-time integration yet — a future PR
1163
+ * can either pre-blur the layer with a Skia shader or
1164
+ * render a black rectangle over the registered ref.
1165
+ */
1166
+ declare function TpkSensitive({ children, mode, style, enabled, testID, }: TpkSensitiveProps): React.ReactElement;
1167
+
1168
+ interface DashboardData {
1169
+ /** All assigned tasks (pending + in_progress + completed). Empty
1170
+ * array if the task endpoint failed — see `partialFailures`. */
1171
+ tasks: TesterTask[];
1172
+ /** Counts derived from `tasks`. Undefined when the task endpoint
1173
+ * failed (the rest of the dashboard still renders). */
1174
+ summary?: TaskListResponse['summary'];
1175
+ /** Tester profile (handle, rating, etc.). null when the profile
1176
+ * endpoint failed or while loading. */
1177
+ profile: TesterProfile | null;
1178
+ /** Current point balance. null when the points endpoint failed
1179
+ * or while loading. */
1180
+ points: TesterPoints | null;
1181
+ /** Endpoints that failed during the last refresh. Set is empty on
1182
+ * a fully-clean fetch. Consumers can render a soft warning per
1183
+ * failed surface instead of blanking the whole screen. */
1184
+ partialFailures: Array<'tasks' | 'profile' | 'points'>;
1185
+ }
1186
+ interface UseDashboardResult {
1187
+ data: DashboardData | null;
1188
+ loading: boolean;
1189
+ error: Error | null;
1190
+ /** Force-refresh from the server. */
1191
+ refresh: () => Promise<void>;
1192
+ }
1193
+ /**
1194
+ * Hook returning the tester-dashboard payload. Fetches once on
1195
+ * mount and exposes a manual refresh hook. Errors are surfaced
1196
+ * but don't throw — render-time guards are the consumer's call.
1197
+ *
1198
+ * Usage:
1199
+ *
1200
+ * const { data, loading, error, refresh } = useTpkDashboard(tpk);
1201
+ *
1202
+ * if (loading) return <ActivityIndicator />;
1203
+ * if (error) return <Text>Error: {error.message}</Text>;
1204
+ * return (
1205
+ * <FlatList
1206
+ * data={data.tasks}
1207
+ * renderItem={({ item }) => <TaskRow task={item} />}
1208
+ * refreshing={loading}
1209
+ * onRefresh={refresh}
1210
+ * />
1211
+ * );
1212
+ */
1213
+ declare function useTpkDashboard(tpk: TpkExpo | null): UseDashboardResult;
1214
+
1215
+ /** Information about the build currently being tested. */
1216
+ interface BuildInfo {
1217
+ id: string;
1218
+ version: string;
1219
+ buildNumber: string;
1220
+ /** ISO-8601 string. Use `new Date(buildInfo.releaseDate)` to parse. */
1221
+ releaseDate: string;
1222
+ /** Headline changelog entries, one per line. */
1223
+ changelog: string[];
1224
+ /** Known issues the dev wants testers to ignore for now. */
1225
+ knownIssues: string[];
1226
+ /** Bugs the tester previously reported that landed in this build. */
1227
+ recentFixes: BugFix[];
1228
+ isActive: boolean;
1229
+ }
1230
+ /** A bug that has been fixed — typically shown in "what's new". */
1231
+ interface BugFix {
1232
+ bugId: string;
1233
+ title: string;
1234
+ description: string;
1235
+ /** ISO-8601 string. */
1236
+ fixedDate: string;
1237
+ /** True if the tester should re-test this fix. */
1238
+ requiresVerification: boolean;
1239
+ /** Has at least one tester verified the fix? */
1240
+ isVerified: boolean;
1241
+ buildVersion?: string;
1242
+ buildNumber?: string;
1243
+ }
1244
+ /**
1245
+ * Focus area surfaced to testers — "spend most of your time here,
1246
+ * here's why, here are the critical paths". Drives the Focus-Areas
1247
+ * card on the Tester Dashboard and the FocusArea-grouped annotation
1248
+ * registry index.
1249
+ */
1250
+ interface FocusArea {
1251
+ id: string;
1252
+ featureName: string;
1253
+ /** Why this area is in focus (1-2 sentences). */
1254
+ reason: string;
1255
+ /** Concrete tester guidance — "tap A, then verify B". */
1256
+ testingGuidance: string;
1257
+ /** Critical paths through the feature to exercise. */
1258
+ criticalPaths: string[];
1259
+ /** 1 (low) → 10 (high). Default 5 in the Flutter SDK. */
1260
+ priority: number;
1261
+ isActive: boolean;
1262
+ }
1263
+ /**
1264
+ * Metadata about a widget visible at the time of a screenshot.
1265
+ * Output of WidgetDiscovery — lets the bug-report UI annotate a
1266
+ * screenshot with "this was a button labelled X at coords Y".
1267
+ *
1268
+ * Flutter's WidgetInfo uses a `Rect` from `dart:ui`; we use a flat
1269
+ * x/y/w/h tuple so the model survives JSON round-trips.
1270
+ */
1271
+ interface WidgetInfo {
1272
+ id: number;
1273
+ type: string;
1274
+ bounds: {
1275
+ x: number;
1276
+ y: number;
1277
+ width: number;
1278
+ height: number;
1279
+ };
1280
+ isVisible: boolean;
1281
+ isInteractive: boolean;
1282
+ text?: string;
1283
+ isSensitive: boolean;
1284
+ semanticLabel?: string;
1285
+ keyLabel?: string;
1286
+ depth: number;
1287
+ }
1288
+ /**
1289
+ * Semver-ish version range used by TaskAnnotation.versionRange to
1290
+ * gate annotations to specific app builds.
1291
+ *
1292
+ * Mirrors the Flutter SDK shape — `min/max/exact` fields produced
1293
+ * by `parseVersionRange()` and a `constraint` for round-tripping
1294
+ * the original user-typed string.
1295
+ *
1296
+ * Supported syntaxes (matched against the Flutter parser):
1297
+ * "1.2.3" → exact
1298
+ * "^1.2.3" → caret (major-locked, ≥ base)
1299
+ * "~1.2.3" → tilde (major+minor locked, ≥ base)
1300
+ * ">=1.0.0 <2.0.0" → explicit min/max
1301
+ * ">=1.0.0" → min-only
1302
+ * "<2.0.0" → max-only
1303
+ */
1304
+ interface VersionRange {
1305
+ min?: string;
1306
+ max?: string;
1307
+ exact?: string;
1308
+ constraint?: string;
1309
+ }
1310
+ /** Parse a semver-ish constraint string into a `VersionRange`. */
1311
+ declare function parseVersionRange(constraint: string): VersionRange;
1312
+ /**
1313
+ * Test whether `version` satisfies `range`. Matches the Flutter
1314
+ * SDK's behaviour: caret matches major, tilde matches major+minor,
1315
+ * `min` is inclusive, `max` is exclusive, `exact` is strict equality.
1316
+ */
1317
+ declare function versionSatisfies(range: VersionRange, version: string): boolean;
1318
+
1319
+ interface TesterDashboardProps {
1320
+ /** SDK client (the same one feeding the rest of the app). */
1321
+ tpk: TpkExpo | null;
1322
+ /** Fired when the user taps a task row. */
1323
+ onTaskPress?: (task: TesterTask) => void;
1324
+ /** Fired by the primary CTA. Hidden when not provided. */
1325
+ onStartTesting?: () => void;
1326
+ /** Outer container override. */
1327
+ style?: StyleProp<ViewStyle>;
1328
+ /** Override the greeting (default uses tester handle or "Tester"). */
1329
+ greeting?: string;
1330
+ /** testID applied to the outer ScrollView. */
1331
+ testID?: string;
1332
+ /** Build the tester is currently exercising. Renders the
1333
+ * Build-Info card (version, changelog, known-issues). */
1334
+ buildInfo?: BuildInfo;
1335
+ /** Focus areas this build wants exercised. Renders the
1336
+ * Focus-Areas card with priority-sorted entries. */
1337
+ focusAreas?: FocusArea[];
1338
+ /** Recently shipped bug fixes — renders a "verify these"
1339
+ * card so testers can confirm prior reports landed. Sourced
1340
+ * from `buildInfo.recentFixes` when not passed explicitly. */
1341
+ recentFixes?: BugFix[];
1342
+ /** Fired when the user taps a focus-area row. */
1343
+ onFocusAreaPress?: (area: FocusArea) => void;
1344
+ /** Fired when the user taps a "verify fix" row. */
1345
+ onVerifyFix?: (fix: BugFix) => void;
1346
+ }
1347
+ /**
1348
+ * Render the tester dashboard. Loading + error states are handled
1349
+ * internally; pass an `onStartTesting` to surface the primary CTA.
1350
+ */
1351
+ declare function TesterDashboard({ tpk, onTaskPress, onStartTesting, style, greeting, testID, buildInfo, focusAreas, recentFixes, onFocusAreaPress, onVerifyFix, }: TesterDashboardProps): React.ReactElement;
1352
+
1353
+ interface ReleaseNote {
1354
+ /** One-line headline ("Swipe-to-delete on bons"). */
1355
+ title: string;
1356
+ /** Optional second line. Keep short — long descriptions push the
1357
+ * task list below the fold. */
1358
+ description?: string;
1359
+ }
1360
+ interface WelcomeTask {
1361
+ /** Stable id — when phase-server lifts task acknowledgement
1362
+ * upstream, this is the key we'll send. */
1363
+ id: string;
1364
+ /** One-line action ("Delete a bon — Swipe or detail-Trash"). */
1365
+ title: string;
1366
+ /** Optional context shown smaller below the title. */
1367
+ description?: string;
1368
+ /** Self-reported estimate. Sums up in the sheet footer. */
1369
+ estimatedMinutes?: number;
1370
+ }
1371
+ interface WelcomeBrief {
1372
+ /** Which build the briefing belongs to. We persist this as the
1373
+ * acknowledgement key so a new version re-prompts the tester. */
1374
+ appVersion: string;
1375
+ releaseNotes: ReleaseNote[];
1376
+ tasks: WelcomeTask[];
1377
+ }
1378
+
1379
+ declare const WELCOME_ACK_STORAGE_KEY = "welcome-ack";
1380
+ /** Minimal storage contract — TpkExpo's `ExpoStorage` satisfies it. */
1381
+ interface WelcomeAckStorage {
1382
+ get<T = unknown>(key: string): Promise<T | null>;
1383
+ set(key: string, value: unknown): Promise<void>;
1384
+ remove(key: string): Promise<void>;
1385
+ }
1386
+ /**
1387
+ * Has the tester already acknowledged this version's welcome sheet?
1388
+ * Returns false on any read error so a flaky storage doesn't trap
1389
+ * the tester in an "already-seen" state forever.
1390
+ */
1391
+ declare function hasWelcomeBriefBeenSeen(storage: WelcomeAckStorage, appVersion: string): Promise<boolean>;
1392
+ /** Stamp this version as acknowledged. Idempotent. */
1393
+ declare function markWelcomeBriefAsSeen(storage: WelcomeAckStorage, appVersion: string): Promise<void>;
1394
+ /** Drop the acknowledgement (e.g. on logout / forgetAuth). */
1395
+ declare function resetWelcomeBriefAck(storage: WelcomeAckStorage): Promise<void>;
1396
+
1397
+ interface TpkWelcomeSheetProps {
1398
+ /** Whether the sheet is rendered. The host typically guards this
1399
+ * with `hasWelcomeBriefBeenSeen` so it shows once per version. */
1400
+ visible: boolean;
1401
+ /** Briefing payload — release notes + tasks for this version. */
1402
+ brief: WelcomeBrief;
1403
+ /** Display name surfaced in the header ("Bonblick"). */
1404
+ productName: string;
1405
+ /** Tester taps "Start" — typically just closes the sheet. */
1406
+ onStart: () => void;
1407
+ /** Optional "Later" escape hatch. When omitted, only Start is shown. */
1408
+ onLater?: () => void;
1409
+ /** Outer modal style override. */
1410
+ style?: StyleProp<ViewStyle>;
1411
+ /** testID applied to the outer scroller. */
1412
+ testID?: string;
1413
+ }
1414
+ declare function TpkWelcomeSheet({ visible, brief, productName, onStart, onLater, style, testID, }: TpkWelcomeSheetProps): React.ReactElement;
1415
+
1416
+ interface TpkOnboardingProps {
1417
+ /** Storage adapter used to persist the done flag + consent. */
1418
+ storage: OnboardingStorage;
1419
+ /** Product name surfaced to the tester ("Bonblick"). */
1420
+ productName?: string;
1421
+ /** Fired after the tester finishes (or skips) the flow. */
1422
+ onComplete: (result: {
1423
+ skipped: boolean;
1424
+ screenshotConsent: boolean;
1425
+ }) => void;
1426
+ /** Outer container override. */
1427
+ style?: StyleProp<ViewStyle>;
1428
+ /** testID applied to the outer container. */
1429
+ testID?: string;
1430
+ }
1431
+ declare function TpkOnboarding({ storage, productName, onComplete, style, testID, }: TpkOnboardingProps): React.ReactElement;
1432
+
1433
+ interface WidgetTourProps {
1434
+ /** Whether the tour is rendered. The host guards this with the
1435
+ * `tpk-widget-tour-seen` flag so it shows once per device. */
1436
+ visible: boolean;
1437
+ /** Fired when the tester finishes ("Los geht's") OR skips
1438
+ * ("Überspringen"). The host persists the seen-flag and then
1439
+ * performs the action the first tap originally intended. */
1440
+ onDone: () => void;
1441
+ /** Outer modal style override. */
1442
+ style?: StyleProp<ViewStyle>;
1443
+ /** testID applied to the card scroller. */
1444
+ testID?: string;
1445
+ }
1446
+ declare function WidgetTour({ visible, onDone, style, testID, }: WidgetTourProps): React.ReactElement;
1447
+
1448
+ declare const WIDGET_TOUR_SEEN_STORAGE_KEY = "tpk-widget-tour-seen";
1449
+ /** Has the tester already seen the first-tap widget tour? */
1450
+ declare function hasSeenWidgetTour(storage: OnboardingStorage): Promise<boolean>;
1451
+ /** Stamp the tour as seen. Idempotent. */
1452
+ declare function markWidgetTourSeen(storage: OnboardingStorage): Promise<void>;
1453
+ /** Drop the seen flag (e.g. on logout / for re-testing the tour). */
1454
+ declare function resetWidgetTourSeen(storage: OnboardingStorage): Promise<void>;
1455
+
1456
+ type TpkLogLevel = 'debug' | 'info' | 'warn' | 'error';
1457
+ interface TpkLogEntry {
1458
+ level: TpkLogLevel;
1459
+ message: string;
1460
+ /** Optional error object for `error` level. */
1461
+ error?: unknown;
1462
+ /** Free-form context bag — recommended for structured fields like
1463
+ * `route`, `userId`, `requestId`. */
1464
+ context?: Record<string, unknown>;
1465
+ /** Wall-clock ms timestamp. */
1466
+ timestamp: number;
1467
+ }
1468
+ type TpkTalkerListener = (entry: TpkLogEntry) => void;
1469
+ interface TpkTalkerOptions {
1470
+ /** Max entries to keep in the in-memory ring. 0 disables history. */
1471
+ maxHistoryItems?: number;
1472
+ /** Mirror entries to `console.{level}`. Default: true in `__DEV__`,
1473
+ * false otherwise. Pass explicit `false` to silence the console
1474
+ * even in development (e.g. for tests). */
1475
+ useConsoleLogs?: boolean;
1476
+ /** Minimum level to record. Below this is dropped. Default 'debug'. */
1477
+ minLevel?: TpkLogLevel;
1478
+ }
1479
+ declare class TpkTalker {
1480
+ private static _instance;
1481
+ /** Lazily-built singleton. Safe to call anywhere. */
1482
+ static get instance(): TpkTalker;
1483
+ /** Idempotent init. Wires global error / unhandledrejection
1484
+ * handlers so anything that throws lands in the same buffer the
1485
+ * tester sees. Pass options to override defaults. */
1486
+ static ensureInitialized(options?: TpkTalkerOptions): TpkTalker;
1487
+ /** Reset for tests. Never call from app code. */
1488
+ static resetInstance(): void;
1489
+ static debug(message: string, context?: Record<string, unknown>): void;
1490
+ static info(message: string, context?: Record<string, unknown>): void;
1491
+ static warn(message: string, context?: Record<string, unknown>): void;
1492
+ static error(message: string, error?: unknown, context?: Record<string, unknown>): void;
1493
+ private maxHistory;
1494
+ private useConsole;
1495
+ private minLevelNum;
1496
+ private entries;
1497
+ private listeners;
1498
+ private uninstallHooks;
1499
+ private constructor();
1500
+ debug(message: string, context?: Record<string, unknown>): void;
1501
+ info(message: string, context?: Record<string, unknown>): void;
1502
+ warn(message: string, context?: Record<string, unknown>): void;
1503
+ error(message: string, error?: unknown, context?: Record<string, unknown>): void;
1504
+ /** Subscribe a sink (Sentry / Crashlytics / Datadog adapter).
1505
+ * Returns an unsubscribe function. */
1506
+ subscribe(listener: TpkTalkerListener): () => void;
1507
+ /** Snapshot of the current ring buffer. Returns a copy. */
1508
+ history(filter?: {
1509
+ level?: TpkLogLevel;
1510
+ since?: number;
1511
+ }): TpkLogEntry[];
1512
+ /** Drop the history (privacy-on-logout / test reset). */
1513
+ clear(): void;
1514
+ /** Tune the history ring without recreating the instance. */
1515
+ setMaxHistoryItems(n: number): void;
1516
+ private record;
1517
+ private installGlobalHooks;
1518
+ private uninstallGlobalHooks;
1519
+ }
1520
+
1521
+ interface DiscoverOptions {
1522
+ /** Include `data-tpk-sensitive` elements (Web only). Default true. */
1523
+ includeSensitive?: boolean;
1524
+ /** Include interactive DOM elements (Web only). Default false —
1525
+ * opt-in because the result can be noisy. */
1526
+ includeInteractive?: boolean;
1527
+ /** Override the registry. Default: TaskAnnotationRegistry.instance. */
1528
+ registry?: TaskAnnotationRegistry;
1529
+ }
1530
+ declare class WidgetDiscovery {
1531
+ private static _instance;
1532
+ static get instance(): WidgetDiscovery;
1533
+ static resetInstance(): void;
1534
+ /**
1535
+ * Discover all testable surfaces currently on screen. Returns
1536
+ * `WidgetInfo` records keyed by an ascending id so order matches
1537
+ * the annotation registration order (Web bonuses appended).
1538
+ */
1539
+ discover(options?: DiscoverOptions): Promise<WidgetInfo[]>;
1540
+ /** Find annotations whose semantic labels include `query`
1541
+ * (case-insensitive substring match). Mirrors Flutter's
1542
+ * WidgetDiscovery.findByLabel. */
1543
+ findByLabel(query: string): WidgetInfo[];
1544
+ }
1545
+ /** Convenience shortcut. */
1546
+ declare const widgetDiscovery: WidgetDiscovery;
1547
+
1548
+ declare function mockBugFixes(): BugFix[];
1549
+ declare function mockBuildInfo(): BuildInfo;
1550
+ declare function mockFocusAreas(): FocusArea[];
1551
+ declare function mockWelcomeTasks(): WelcomeTask[];
1552
+ declare function mockWelcomeBrief(): WelcomeBrief;
1553
+ declare function mockWidgets(): WidgetInfo[];
1554
+
1555
+ type FeedbackCategory = 'general' | 'featureRequest' | 'improvement' | 'complaint' | 'praise';
1556
+ interface GeneralFeedbackDialogProps {
1557
+ visible: boolean;
1558
+ tpk?: Pick<TpkExpo, 'submitBug'> | null;
1559
+ /** What screen the user was on when they opened the dialog. */
1560
+ currentScreen?: string;
1561
+ onClose: () => void;
1562
+ onSubmitted?: (result: SubmitBugResult) => void;
1563
+ onError?: (error: Error) => void;
1564
+ style?: StyleProp<ViewStyle>;
1565
+ }
1566
+ declare function GeneralFeedbackDialog({ visible, tpk, currentScreen, onClose, onSubmitted, onError, style, }: GeneralFeedbackDialogProps): React.ReactElement;
1567
+
1568
+ type MaterialIconName = string;
1569
+ /**
1570
+ * Semantic icon names used by the SDK. Map to MaterialIcons glyph
1571
+ * names by default; consumers can override via TpkIconsContext.
1572
+ */
1573
+ type TpkIconName = 'bug_report' | 'feedback' | 'dashboard' | 'session_end' | 'voice' | 'voice_off' | 'close' | 'check' | 'star_filled' | 'star_outline' | 'camera' | 'image' | 'attachment' | 'music_note' | 'language' | 'rocket' | 'lightbulb' | 'trend_up' | 'frown' | 'smile' | 'palette' | 'speed_slow' | 'crash' | 'sparkle' | 'cloud_upload' | 'refresh' | 'edit_pen' | 'shape_rect' | 'shape_circle' | 'shape_arrow' | 'text' | 'blur';
1574
+ type TpkIconOverrideMap = Partial<Record<TpkIconName, MaterialIconName>>;
1575
+ declare function TpkIconsProvider({ icons, children, }: {
1576
+ icons: TpkIconOverrideMap;
1577
+ children: ReactNode;
1578
+ }): React.JSX.Element;
1579
+ interface TpkIconProps {
1580
+ name: TpkIconName;
1581
+ size?: number;
1582
+ color?: string;
1583
+ style?: TextStyle;
1584
+ }
1585
+ declare function TpkIcon({ name, size, color, style, }: TpkIconProps): React.ReactElement;
1586
+
1587
+ interface TpkTheme {
1588
+ primary: string;
1589
+ errorColour: string;
1590
+ surface: string;
1591
+ onSurface: string;
1592
+ }
1593
+ declare const DEFAULT_TPK_THEME: TpkTheme;
1594
+ declare function TpkThemeProvider({ theme, children, }: {
1595
+ theme?: Partial<TpkTheme>;
1596
+ children: ReactNode;
1597
+ }): React.JSX.Element;
1598
+ declare function useTpkTheme(): TpkTheme;
1599
+
1600
+ interface AnnotatedScreenshotResult {
1601
+ /** Base64 (no data-URI prefix). */
1602
+ base64: string;
1603
+ mimeType: 'image/png' | 'image/jpeg';
1604
+ byteLength: number;
1605
+ }
1606
+ interface ScreenshotAnnotationEditorProps {
1607
+ visible: boolean;
1608
+ /** Background image as a data-URI or remote/local URI. */
1609
+ imageUri: string;
1610
+ /** Natural pixel width of the source image. Used for the canvas
1611
+ * aspect ratio + coordinate normalisation. */
1612
+ imageWidth: number;
1613
+ /** Natural pixel height of the source image. */
1614
+ imageHeight: number;
1615
+ onSave: (result: AnnotatedScreenshotResult) => void | Promise<void>;
1616
+ onCancel: () => void;
1617
+ /** Output format. Default 'png' (lossless, matches Flutter). */
1618
+ format?: 'png' | 'jpg';
1619
+ /** JPG quality 0-1. Ignored for png. Default 0.9. */
1620
+ quality?: number;
1621
+ style?: StyleProp<ViewStyle>;
1622
+ testID?: string;
1623
+ }
1624
+ declare function ScreenshotAnnotationEditor({ visible, imageUri, imageWidth, imageHeight, onSave, onCancel, format, quality, style, testID, }: ScreenshotAnnotationEditorProps): React.ReactElement;
1625
+
1626
+ interface VoiceExtractAudio {
1627
+ /** Base64 audio bytes — no data-URI prefix. */
1628
+ base64: string;
1629
+ /** MIME type of the audio. Whisper accepts m4a / aac / wav / mp3 /
1630
+ * webm; the server forwards whatever we send. */
1631
+ mimeType: string;
1632
+ /** Optional ISO-639-1 language hint forwarded to Whisper. When
1633
+ * set, transcription skips language detection and treats the
1634
+ * audio as the given language — faster + more accurate when the
1635
+ * tester knows their own language. Omit to let Whisper detect. */
1636
+ language?: 'de' | 'en';
1637
+ }
1638
+ interface VoiceExtractResult {
1639
+ /** Raw Whisper transcript. */
1640
+ transcript: string;
1641
+ title: string;
1642
+ description: string;
1643
+ expectedBehavior: string;
1644
+ actualBehavior: string;
1645
+ /** Server enum — same set the BugReportSheet's Frequency chips use. */
1646
+ frequency: 'always' | 'often' | 'sometimes' | 'rarely';
1647
+ /**
1648
+ * Voice-bug split (A2): ISO-639-1 code the tester spoke in. The
1649
+ * server doesn't echo it, so we carry the request hint through —
1650
+ * it rides to submit as the O-Ton language label.
1651
+ */
1652
+ sourceLanguage?: string;
1653
+ }
1654
+ /**
1655
+ * Send an audio recording to the voice-extract endpoint and return
1656
+ * the extracted bug-report fields. Resolves with structured data on
1657
+ * success; throws on transport / server error so the caller can
1658
+ * surface a retry UI.
1659
+ */
1660
+ declare function extractVoiceBug(tpk: Pick<TpkExpo, 'api'>, audio: VoiceExtractAudio): Promise<VoiceExtractResult>;
1661
+
1662
+ type VoiceClassification = 'bug' | 'featureRequest' | 'idea' | 'issue';
1663
+ /** Per-string overrides — pass to host-localise. Any unset value
1664
+ * falls back to the German default (matches the Flutter consumer). */
1665
+ interface VoiceBugStrings {
1666
+ languagePickerLabel?: string;
1667
+ classificationBug?: string;
1668
+ classificationFeature?: string;
1669
+ classificationIdea?: string;
1670
+ classificationIssue?: string;
1671
+ idleHeadline?: string;
1672
+ idleDescription?: string;
1673
+ recordingHeadline?: string;
1674
+ recordingDescription?: string;
1675
+ processingHeadline?: string;
1676
+ processingDescription?: string;
1677
+ errorHeadline?: string;
1678
+ errorDescriptionFallback?: string;
1679
+ extractedHeadline?: string;
1680
+ extractedDescription?: string;
1681
+ cancel?: string;
1682
+ retry?: string;
1683
+ useExtracted?: string;
1684
+ rerecord?: string;
1685
+ }
1686
+ interface VoiceBugInputSheetProps {
1687
+ visible: boolean;
1688
+ tpk: Pick<TpkExpo, 'api'> | null;
1689
+ onCancel: () => void;
1690
+ /** Fires with the extracted fields PLUS the chosen classification
1691
+ * (Bug / Feature / Idea / Issue). The host typically passes both
1692
+ * on to BugReportSheet's initialDraft prop. */
1693
+ onExtracted: (result: VoiceExtractResult, classification: VoiceClassification) => void;
1694
+ /** Max recording length in seconds. Default 60. */
1695
+ maxSeconds?: number;
1696
+ /** Accent colour for the mic + active chip. Default `#D83232`
1697
+ * (bug-red). Hosts that want a brand-tint can override. */
1698
+ accentColor?: string;
1699
+ /** Host-side string overrides. Any missing key falls back to the
1700
+ * German default copy. */
1701
+ strings?: VoiceBugStrings;
1702
+ style?: StyleProp<ViewStyle>;
1703
+ testID?: string;
1704
+ }
1705
+ declare function VoiceBugInputSheet({ visible, tpk, onCancel, onExtracted, maxSeconds, accentColor, strings, style, testID, }: VoiceBugInputSheetProps): React.ReactElement;
1706
+ /** Maps the sheet's classification onto the BugReportSheet's
1707
+ * BugReportType union. Exported so the host can call it when
1708
+ * building the initialDraft for the bug sheet. */
1709
+ declare function classificationToBugType(c: VoiceClassification): BugReportType;
1710
+
1711
+ interface SessionEndStats {
1712
+ /** Active session duration in seconds. Drives the foregroundSeconds
1713
+ * argument to endSession + the "Time spent" stats row. */
1714
+ durationSeconds: number;
1715
+ /** Distinct screens the tester touched this session. Optional —
1716
+ * comes from getUniqueScreens() if the host wires it. */
1717
+ screensVisited?: number;
1718
+ /** Bug reports filed this session. Optional — the host can pass
1719
+ * the local counter; we don't query the server for it. */
1720
+ bugsReported?: number;
1721
+ /** Tasks completed this session. Forwarded to endSession. */
1722
+ tasksCompleted?: number;
1723
+ }
1724
+ interface SessionEndDialogProps {
1725
+ visible: boolean;
1726
+ tpk?: Pick<TpkExpo, 'endSession' | 'submitBug'> | null;
1727
+ /** Stats to display + forward to the server. When omitted, the
1728
+ * stats section just shows zeroes. */
1729
+ stats?: SessionEndStats;
1730
+ /** Screen the user was on when they tapped End Session. */
1731
+ currentScreen?: string;
1732
+ onClose: () => void;
1733
+ onEnded?: () => void;
1734
+ onError?: (error: Error) => void;
1735
+ style?: StyleProp<ViewStyle>;
1736
+ }
1737
+ declare function SessionEndDialog({ visible, tpk, stats, currentScreen, onClose, onEnded, onError, style, }: SessionEndDialogProps): React.ReactElement;
1738
+
1739
+ interface MyBugsSheetProps {
1740
+ visible: boolean;
1741
+ tpk: TpkExpo | null;
1742
+ onClose: () => void;
1743
+ }
1744
+ declare function MyBugsSheet({ visible, tpk, onClose, }: MyBugsSheetProps): React.ReactElement;
1745
+
1746
+ interface SessionDetailsSheetProps {
1747
+ visible: boolean;
1748
+ tpk: TpkExpo | null;
1749
+ onClose: () => void;
1750
+ /** Earnings model (defaults match the FAB header + Flutter screen). */
1751
+ earningsBaseAmount?: number;
1752
+ earningsPerMinuteRate?: number;
1753
+ earningsCurrency?: string;
1754
+ }
1755
+ declare function SessionDetailsSheet({ visible, tpk, onClose, earningsBaseAmount, earningsPerMinuteRate, earningsCurrency, }: SessionDetailsSheetProps): React.ReactElement;
1756
+
1757
+ interface StatusStyle {
1758
+ label: string;
1759
+ color: string;
1760
+ }
1761
+ /** Label + colour for a bug status. Unknown statuses fall back to the raw
1762
+ * status string on a neutral blue-grey. */
1763
+ declare function bugStatusStyle(status: string): StatusStyle;
1764
+ /** German severity label, or the raw value if unknown, or null if absent. */
1765
+ declare function bugSeverityLabel(severity?: string | null): string | null;
1766
+
1767
+ interface NotificationsSheetProps {
1768
+ visible: boolean;
1769
+ tpk: TpkExpo | null;
1770
+ onClose: () => void;
1771
+ /** Called with the new unread count after load + after marking read, so
1772
+ * the host can refresh the FAB badge. */
1773
+ onUnreadChange?: (count: number) => void;
1774
+ }
1775
+ declare function NotificationsSheet({ visible, tpk, onClose, onUnreadChange, }: NotificationsSheetProps): React.ReactElement;
1776
+
1777
+ interface InviteCodeScreenProps {
1778
+ visible: boolean;
1779
+ tpk: TpkExpo | null;
1780
+ /** Called after a successful login — the host typically hides the screen. */
1781
+ onSuccess?: () => void;
1782
+ /** Optional cancel/close. When omitted, no close affordance is shown. */
1783
+ onClose?: () => void;
1784
+ /** Optional product/project name for the heading. */
1785
+ projectName?: string;
1786
+ }
1787
+ declare function InviteCodeScreen({ visible, tpk, onSuccess, onClose, projectName, }: InviteCodeScreenProps): React.ReactElement;
1788
+
1789
+ interface TesterPayKitWrapperProps {
1790
+ children: ReactNode;
1791
+ /** Initialized TpkExpo client. When null, the FAB still renders
1792
+ * but every action that needs the server stays disabled. */
1793
+ tpk: TpkExpo | null;
1794
+ /** Master switch. When false the wrapper renders `children`
1795
+ * unchanged — same shape as Flutter's `enableWrapper: false`
1796
+ * demo mode. */
1797
+ enableWrapper?: boolean;
1798
+ /** Enable accelerometer-based shake-to-report on native. Default
1799
+ * true; web ignores it (no DeviceMotion permission gate by
1800
+ * default). Requires expo-sensors as a peer dep — falls back to
1801
+ * no-op when the module isn't installed. */
1802
+ enableShake?: boolean;
1803
+ /** Threshold above which we consider it a shake (gravity units).
1804
+ * Flutter default is 2.7. Lower → more sensitive. */
1805
+ shakeThresholdG?: number;
1806
+ /** Outer container override. */
1807
+ style?: StyleProp<ViewStyle>;
1808
+ onShowDebugLogs?: () => void;
1809
+ notificationCount?: number;
1810
+ onFlushCachedCrashes?: () => Promise<number> | number;
1811
+ retestCount?: number;
1812
+ onShowRetests?: () => void;
1813
+ onViewDashboard?: () => void;
1814
+ /** AI-Tester support. When all three are provided, the FAB shows an
1815
+ * "Auto Test (AI)" menu entry that opens the AiRemoteControl
1816
+ * surface. Phase-1 demo wiring: only the developer / coordinator
1817
+ * ships these in dev builds — production-grade wiring (per-tester
1818
+ * invitation) comes in Phase 2. */
1819
+ aiCoordinatorToken?: string;
1820
+ aiProjectId?: string;
1821
+ aiApiBaseUrl?: string;
1822
+ /** Currently active route — flows through to bug reports. */
1823
+ currentScreen?: string;
1824
+ /** When the session started — drives the earnings clock + the
1825
+ * duration tile on SessionEndDialog. Auto-stamps to mount-time
1826
+ * if omitted. */
1827
+ sessionStartedAt?: Date;
1828
+ /** Optional brand-tint overrides. Unset tokens fall back to the
1829
+ * bug-red + slate defaults. See `TpkTheme` for the four
1830
+ * supported tokens. */
1831
+ theme?: Partial<TpkTheme>;
1832
+ testID?: string;
1833
+ }
1834
+ declare function TesterPayKitWrapper({ children, tpk, enableWrapper, enableShake, shakeThresholdG, style, onShowDebugLogs, notificationCount, onFlushCachedCrashes, retestCount, onShowRetests, onViewDashboard, currentScreen, sessionStartedAt, aiCoordinatorToken, aiProjectId, aiApiBaseUrl, theme, testID, }: TesterPayKitWrapperProps): React.ReactElement;
1835
+
1836
+ interface TpkAnnotatedProps {
1837
+ /** Task this element belongs to. */
1838
+ task: string;
1839
+ /** Optional grouping under a focus area. */
1840
+ focusArea?: string;
1841
+ /** Semantic labels for AI / discovery (e.g. ['login', 'primary-cta']). */
1842
+ labels?: string[];
1843
+ /** What action progresses the task. Default 'on-tap'. */
1844
+ completionTrigger?: CompletionTrigger;
1845
+ /** How many interactions before completion. Default 1. */
1846
+ requiredInteractions?: number;
1847
+ /** Optional widget type hint ("Button", "TextInput"). Auto-detected when possible. */
1848
+ elementType?: string;
1849
+ /** Stable identifier; if omitted we read the child's testID prop. */
1850
+ elementKey?: string;
1851
+ /** App version this annotation applies to. */
1852
+ versionRange?: string;
1853
+ /** Free-form bag forwarded to the registry. */
1854
+ metadata?: Record<string, unknown>;
1855
+ /** Exactly one child — gets ref-forwarded + auto-instrumented. */
1856
+ children: React.ReactElement;
1857
+ }
1858
+ /**
1859
+ * Wrap an element to register it with the task-annotation registry.
1860
+ *
1861
+ * <TpkAnnotated task="task-onboarding-1" labels={['signup']} completionTrigger="on-tap">
1862
+ * <Button title="Sign up" onPress={handleSignup} />
1863
+ * </TpkAnnotated>
1864
+ *
1865
+ * The wrapped child's `onPress` / `onChangeText` handlers are
1866
+ * intercepted to call `recordInteraction` automatically when the
1867
+ * configured trigger matches.
1868
+ */
1869
+ declare function TpkAnnotated({ task, focusArea, labels, completionTrigger, requiredInteractions, elementType, elementKey, versionRange, metadata, children, }: TpkAnnotatedProps): React.ReactElement;
1870
+ interface UseTaskAnnotationOptions {
1871
+ taskId: string;
1872
+ focusAreaId?: string;
1873
+ semanticLabels?: string[];
1874
+ completionTrigger?: CompletionTrigger;
1875
+ requiredInteractionCount?: number;
1876
+ elementType?: string;
1877
+ elementKey?: string;
1878
+ versionRange?: string;
1879
+ metadata?: Record<string, unknown>;
1880
+ }
1881
+ interface UseTaskAnnotationResult {
1882
+ /** Attach to your component: `<View ref={ref} />`. */
1883
+ ref: React.MutableRefObject<unknown>;
1884
+ /** Current annotation id (null while not registered). */
1885
+ id: string | null;
1886
+ /** Manually record an interaction. */
1887
+ recordInteraction: () => void;
1888
+ }
1889
+ /**
1890
+ * Imperative hook for cases where the JSX wrapper doesn't fit
1891
+ * (custom components, conditional rendering, headless logic).
1892
+ *
1893
+ * const { ref, recordInteraction } = useTaskAnnotation({
1894
+ * taskId: 'task-1', completionTrigger: 'manual',
1895
+ * });
1896
+ *
1897
+ * <ScrollView ref={ref} onScroll={() => recordInteraction()} />
1898
+ */
1899
+ declare function useTaskAnnotation(options: UseTaskAnnotationOptions): UseTaskAnnotationResult;
1900
+
1901
+ type AnnotationColor = string;
1902
+ interface AnnotationStyle {
1903
+ /** Stroke colour for outlines + freehand paths. Default '#FF3B30'. */
1904
+ color: AnnotationColor;
1905
+ /** Stroke width in CSS pixels. Default 4. */
1906
+ strokeWidth: number;
1907
+ /** Optional fill colour (rect / circle / text bg). */
1908
+ fill?: AnnotationColor;
1909
+ /** Opacity 0–1. Default 1. */
1910
+ opacity?: number;
1911
+ }
1912
+ interface Point {
1913
+ x: number;
1914
+ y: number;
1915
+ }
1916
+ interface RectShape {
1917
+ kind: 'rect';
1918
+ id: string;
1919
+ x: number;
1920
+ y: number;
1921
+ width: number;
1922
+ height: number;
1923
+ style: AnnotationStyle;
1924
+ }
1925
+ interface CircleShape {
1926
+ kind: 'circle';
1927
+ id: string;
1928
+ cx: number;
1929
+ cy: number;
1930
+ r: number;
1931
+ style: AnnotationStyle;
1932
+ }
1933
+ interface ArrowShape {
1934
+ kind: 'arrow';
1935
+ id: string;
1936
+ from: Point;
1937
+ to: Point;
1938
+ /** Arrow head size in CSS pixels. Default 12. */
1939
+ headSize?: number;
1940
+ style: AnnotationStyle;
1941
+ }
1942
+ interface PathShape {
1943
+ kind: 'path';
1944
+ id: string;
1945
+ points: Point[];
1946
+ style: AnnotationStyle;
1947
+ }
1948
+ interface TextShape {
1949
+ kind: 'text';
1950
+ id: string;
1951
+ x: number;
1952
+ y: number;
1953
+ text: string;
1954
+ fontSize: number;
1955
+ style: AnnotationStyle;
1956
+ }
1957
+ /** Pixelate / blur rectangle — used for PII redaction. */
1958
+ interface BlurShape {
1959
+ kind: 'blur';
1960
+ id: string;
1961
+ x: number;
1962
+ y: number;
1963
+ width: number;
1964
+ height: number;
1965
+ /** Pixel block size — bigger = chunkier. Default 16. */
1966
+ blockSize?: number;
1967
+ }
1968
+ type AnnotationShape = RectShape | CircleShape | ArrowShape | PathShape | TextShape | BlurShape;
1969
+ declare const DEFAULT_STYLE: AnnotationStyle;
1970
+ /** Pre-defined palette used by the editor's quick-pick UI. */
1971
+ declare const ANNOTATION_PALETTE: AnnotationColor[];
1972
+ /** Build an empty document the editor can mutate. */
1973
+ declare function emptyAnnotationDoc(): AnnotationShape[];
1974
+ /**
1975
+ * Compress a freehand path with the Ramer–Douglas–Peucker
1976
+ * algorithm. Pure freehand emits one point per touch-move, which
1977
+ * can be hundreds of points — RDP keeps the perceptual shape
1978
+ * while trimming 70-90% of the data. Tolerance is in pixels.
1979
+ */
1980
+ declare function simplifyPath(points: Point[], tolerance?: number): Point[];
1981
+ /**
1982
+ * Convert a path's points to an SVG `d` attribute. Used both by
1983
+ * TpkAnnotationOverlay and by the server's headless renderer
1984
+ * when it needs to re-flatten the annotation later.
1985
+ */
1986
+ declare function pathToSvgD(points: Point[]): string;
1987
+ /** Compute the head triangle points for an arrow shape. */
1988
+ declare function arrowHeadPoints(arrow: ArrowShape): Point[];
1989
+
1990
+ /** Tool the user is currently drawing with. */
1991
+ type AnnotationTool = 'select' | 'rect' | 'circle' | 'arrow' | 'freehand' | 'text' | 'blur';
1992
+ interface TpkAnnotationOverlayProps {
1993
+ /** Background image source — base64 data URI or local URI. */
1994
+ imageUri: string;
1995
+ /** Image natural width (used to normalise touch coordinates). */
1996
+ imageWidth: number;
1997
+ /** Image natural height. */
1998
+ imageHeight: number;
1999
+ /** Active drawing tool. */
2000
+ tool: AnnotationTool;
2001
+ /** Current style applied to new shapes. */
2002
+ style?: AnnotationStyle;
2003
+ /** Initial shapes (for resuming a draft). */
2004
+ initialShapes?: AnnotationShape[];
2005
+ /** Fired whenever the shape list changes. */
2006
+ onShapesChange?: (shapes: AnnotationShape[]) => void;
2007
+ /** Text content used when tool='text'. */
2008
+ textValue?: string;
2009
+ }
2010
+ interface TpkAnnotationOverlayHandle {
2011
+ /** Current shape list. */
2012
+ getShapes(): AnnotationShape[];
2013
+ /** Replace the shape list (for redo / clear / undo stacks). */
2014
+ setShapes(shapes: AnnotationShape[]): void;
2015
+ /** Remove the last-added shape. */
2016
+ undo(): void;
2017
+ /** Wipe all shapes. */
2018
+ clear(): void;
2019
+ /**
2020
+ * Flatten the current view to a base64 PNG via
2021
+ * react-native-view-shot. Returns null if view-shot is not
2022
+ * installed.
2023
+ */
2024
+ finalize(opts?: {
2025
+ format?: 'png' | 'jpg';
2026
+ quality?: number;
2027
+ }): Promise<{
2028
+ base64: string;
2029
+ mimeType: 'image/png' | 'image/jpeg';
2030
+ byteLength: number;
2031
+ } | null>;
2032
+ }
2033
+ /**
2034
+ * Imperative drawing surface. Pair with your own toolbar that
2035
+ * toggles `tool` + `style` props.
2036
+ *
2037
+ * const editor = useRef<TpkAnnotationOverlayHandle>(null);
2038
+ * <TpkAnnotationOverlay ref={editor} tool={tool} ... />
2039
+ * const result = await editor.current?.finalize();
2040
+ * if (result) await uploadScreenshotAttachment(tpk.api, bugId, result);
2041
+ */
2042
+ declare const TpkAnnotationOverlay: React.ForwardRefExoticComponent<TpkAnnotationOverlayProps & React.RefAttributes<TpkAnnotationOverlayHandle>>;
2043
+
2044
+ type RecordingState = 'idle' | 'recording' | 'stopped' | 'unsupported';
2045
+ interface RecordingOptions {
2046
+ /** Hard cap in seconds. Default 30. */
2047
+ maxDurationSeconds?: number;
2048
+ /** Record microphone audio. Default false. */
2049
+ mic?: boolean;
2050
+ /** Output video FPS. Default 30. */
2051
+ fps?: number;
2052
+ /** Video bitrate. Default 1_000_000 (1 Mbps). */
2053
+ bitrate?: number;
2054
+ /** Output width — defaults to device width. */
2055
+ width?: number;
2056
+ /** Output height — defaults to device height. */
2057
+ height?: number;
2058
+ }
2059
+ interface RecordingResult {
2060
+ /** Local file URI (file://...). */
2061
+ uri: string;
2062
+ /** Approximate file size in bytes. Server validates the real size. */
2063
+ fileSize: number;
2064
+ /** Recording duration in milliseconds. */
2065
+ durationMs: number;
2066
+ /** Always video/mp4 from react-native-record-screen. */
2067
+ mimeType: 'video/mp4';
2068
+ }
2069
+ interface RecordingFileReader {
2070
+ readFileAsBase64(uri: string): Promise<string | null>;
2071
+ readFileSize(uri: string): Promise<number>;
2072
+ }
2073
+ /**
2074
+ * Imperative recorder. Hold one instance per session — its `state`
2075
+ * field tracks the current phase so a UI can render start / stop
2076
+ * buttons without re-asking the lib.
2077
+ *
2078
+ * const recorder = new ScreenRecorder();
2079
+ * await recorder.start({ maxDurationSeconds: 30 });
2080
+ * // …user reproduces the bug…
2081
+ * const clip = await recorder.stop();
2082
+ * if (clip) await recorder.uploadAsAttachment(tpk.api, bugId, clip);
2083
+ */
2084
+ declare class ScreenRecorder {
2085
+ private readonly fileReader;
2086
+ state: RecordingState;
2087
+ private startedAt;
2088
+ private timeoutHandle;
2089
+ private onAutoStop?;
2090
+ constructor(fileReader?: RecordingFileReader);
2091
+ /** Probe support before showing recording controls in your UI. */
2092
+ isSupported(): Promise<boolean>;
2093
+ /** Start recording. Returns false if not supported / already running. */
2094
+ start(options?: RecordingOptions, onAutoStop?: () => void): Promise<boolean>;
2095
+ /**
2096
+ * Stop the recording and return its metadata. Returns null if
2097
+ * not recording (and clears any pending timeout regardless).
2098
+ */
2099
+ stop(): Promise<RecordingResult | null>;
2100
+ /** Discard the recorded clip (delete temp file). */
2101
+ discard(): Promise<void>;
2102
+ /**
2103
+ * Read the recorded clip from disk and POST it as an attachment
2104
+ * on an existing bug report. The server's attachments endpoint
2105
+ * accepts base64 fileData regardless of media type, so a single
2106
+ * code path covers screenshots + videos.
2107
+ */
2108
+ uploadAsAttachment(api: TesterPayKitApiClient, bugReportId: string, recording: RecordingResult, fileName?: string): Promise<BugReportAttachmentResponse | null>;
2109
+ }
2110
+
2111
+ type VoiceNoteState = 'idle' | 'recording' | 'stopped' | 'unsupported';
2112
+ interface VoiceNoteRecorderLike {
2113
+ uri?: string | null;
2114
+ currentTime?: number;
2115
+ prepareToRecordAsync?: () => Promise<unknown>;
2116
+ record?: () => unknown;
2117
+ stop?: () => Promise<unknown> | unknown;
2118
+ }
2119
+ interface VoiceNoteFileReader {
2120
+ readFileAsBase64(uri: string): Promise<string | null>;
2121
+ readFileSize(uri: string): Promise<number>;
2122
+ }
2123
+ interface VoiceNoteRecorderOptions extends Partial<VoiceNoteFileReader> {
2124
+ /**
2125
+ * Pass the object returned by expo-audio's useAudioRecorder().
2126
+ * Kept structural so the package does not hard-import expo-audio.
2127
+ */
2128
+ recorder?: VoiceNoteRecorderLike | null;
2129
+ }
2130
+ interface VoiceNoteResult {
2131
+ /** Local file URI (file://...). */
2132
+ uri: string;
2133
+ /** Approximate file size in bytes. Server validates the real size. */
2134
+ fileSize: number;
2135
+ /** Recording duration in milliseconds. */
2136
+ durationMs: number;
2137
+ /** M4A/AAC voice notes are uploaded as audio/mp4. */
2138
+ mimeType: 'audio/mp4';
2139
+ }
2140
+ declare class VoiceNoteRecorder {
2141
+ state: VoiceNoteState;
2142
+ private readonly recorder;
2143
+ private readonly fileReader;
2144
+ private startedAt;
2145
+ constructor(options?: VoiceNoteRecorderOptions);
2146
+ isSupported(): Promise<boolean>;
2147
+ start(): Promise<boolean>;
2148
+ stop(): Promise<VoiceNoteResult | null>;
2149
+ uploadAsAttachment(api: TesterPayKitApiClient, bugReportId: string, note: VoiceNoteResult, fileName?: string): Promise<BugReportAttachmentResponse | null>;
2150
+ }
2151
+
2152
+ interface EarningsData {
2153
+ summary: EarningsSummary;
2154
+ recentPayouts: PayoutRecord[];
2155
+ }
2156
+ interface UseEarningsResult {
2157
+ data: EarningsData | null;
2158
+ loading: boolean;
2159
+ error: Error | null;
2160
+ refresh: () => Promise<void>;
2161
+ }
2162
+ /**
2163
+ * Hook returning the tester's earnings summary + recent payouts.
2164
+ *
2165
+ * const { data, loading, refresh } = useTpkEarnings(tpk);
2166
+ *
2167
+ * if (data) {
2168
+ * return <Text>Balance: {data.summary.currentBalance} €</Text>;
2169
+ * }
2170
+ */
2171
+ declare function useTpkEarnings(tpk: TpkExpo | null, options?: {
2172
+ payoutLimit?: number;
2173
+ }): UseEarningsResult;
2174
+
2175
+ export { ANNOTATION_PALETTE, type AnnotatedElementInfo, type AnnotatedScreenshotResult, type AnnotationColor, type AnnotationEvent, type AnnotationEventType, type AnnotationInteraction, type AnnotationListener, type AnnotationShape, type AnnotationStyle, type AnnotationTool, type AppSnapshot, type ArrowShape, AttachmentQueue, type AttachmentQueueFlushOptions, type BlurShape, type Breadcrumb, Breadcrumbs, type BugFix, type BugReportDraft, BugReportSheet, type BugReportSheetProps, type BuildInfo, type CachedCrash, type CaptureViewOptions, type CircleShape, type CompletionTrigger, type CrashHandlerOptions, type CrashInfo, CrashQueue, type CreateBugReportDraftInput, DEFAULT_STYLE, DEFAULT_TPK_THEME, type DashboardData, type DeviceSnapshot, type DiscoverOptions, type EarningsData, type EngagedMinutesInput, ExpoStorage, type FeedbackCategory, FloatingFeedbackButton, type FloatingFeedbackButtonProps, type FlushTelemetryResult, type FocusArea, GeneralFeedbackDialog, type GeneralFeedbackDialogProps, INTERACTION_NAV_WEIGHT, type InstallNetworkCaptureOptions, type InteractionBounds, type InteractionType, InviteCodeScreen, type InviteCodeScreenProps, MIN_INTERACTIONS_PER_ACTIVE_MINUTE, MyBugsSheet, type MyBugsSheetProps, NotificationsSheet, type NotificationsSheetProps, ONBOARDING_DONE_STORAGE_KEY, type OnboardingStorage, type PathShape, type PeriodFilter, type Point, type QueueFlushOptions, type QueueFlushResult, type RecordInteractionDetails, type RecordingOptions, type RecordingResult, type RecordingState, type RectShape, type RegisterAnnotationInput, type ReleaseNote, SCREENSHOT_CONSENT_STORAGE_KEY, ScreenRecorder, ScreenshotAnnotationEditor, type ScreenshotAnnotationEditorProps, type ScreenshotResult, type SensitiveMaskingMode, SessionDetailsSheet, type SessionDetailsSheetProps, SessionEndDialog, type SessionEndDialogProps, type SessionEndStats, type SessionStatsSnapshot, type StatusStyle, type SubmitBugInput, SubmitQueue, type TaskAnnotation, TaskAnnotationRegistry, type TaskInteractionSummary, type TaskProgress, TesterDashboard, type TesterDashboardProps, type TesterPayKitContextValue, TesterPayKitProvider, type TesterPayKitProviderProps, TesterPayKitWrapper, type TesterPayKitWrapperProps, type TextShape, TpkAnnotated, type TpkAnnotatedProps, TpkAnnotationOverlay, type TpkAnnotationOverlayHandle, type TpkAnnotationOverlayProps, TpkExpo, type TpkExpoConfig, TpkIcon, type TpkIconName, type TpkIconOverrideMap, type TpkIconProps, TpkIconsProvider, type TpkLogEntry, type TpkLogLevel, TpkOnboarding, type TpkOnboardingProps, TpkSensitive, type TpkSensitiveProps, type TpkStorage, TpkTalker, type TpkTalkerListener, type TpkTalkerOptions, type TpkTheme, TpkThemeProvider, TpkWelcomeSheet, type TpkWelcomeSheetProps, type UseDashboardResult, type UseEarningsResult, type UseShakeOptions, type UseTaskAnnotationOptions, type UseTaskAnnotationResult, type VersionRange, VoiceBugInputSheet, type VoiceBugInputSheetProps, type VoiceBugStrings, type VoiceClassification, type VoiceExtractAudio, type VoiceExtractResult, type VoiceNoteFileReader, VoiceNoteRecorder, type VoiceNoteRecorderLike, type VoiceNoteRecorderOptions, type VoiceNoteResult, type VoiceNoteState, WELCOME_ACK_STORAGE_KEY, WIDGET_TOUR_SEEN_STORAGE_KEY, type WelcomeAckStorage, type WelcomeBrief, type WelcomeTask, WidgetDiscovery, type WidgetInfo, WidgetTour, type WidgetTourProps, annotations, applySensitiveRedaction, arrowHeadPoints, beginNativeCapture, bugSeverityLabel, bugStatusStyle, canSubmitBugReportDraft, captureView, classificationToBugType, createBugReportDraft, deriveTaskProgress, emptyAnnotationDoc, endNativeCapture, engagedMinutes, extractVoiceBug, findAssignmentForTask, getAppSnapshot, getDeviceSnapshot, getEventCounts, getNativeCaptureMode, getSessionStats, getUniqueScreens, hasCompletedOnboarding, hasScreenshotConsent, hasSeenWidgetTour, hasWelcomeBriefBeenSeen, installCrashHandler, installNetworkCapture, markOnboardingComplete, markWelcomeBriefAsSeen, markWidgetTourSeen, mockBugFixes, mockBuildInfo, mockFocusAreas, mockWelcomeBrief, mockWelcomeTasks, mockWidgets, parseVersionRange, pathToSvgD, resetOnboardingState, resetWelcomeBriefAck, resetWidgetTourSeen, simplifyPath, submitBugReportDraft, subscribeNativeCaptureMode, uploadScreenshotAttachment, useShake, useTaskAnnotation, useTesterPayKit, useTpkDashboard, useTpkEarnings, useTpkTheme, versionSatisfies, widgetDiscovery, withNativeCapture };