@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.
- package/CHANGELOG.md +47 -0
- package/README.md +290 -0
- package/dist/chunk-AGHDTD54.mjs +64 -0
- package/dist/index.d.mts +2175 -0
- package/dist/index.d.ts +2175 -0
- package/dist/index.js +10542 -0
- package/dist/index.mjs +10522 -0
- package/dist/network-TY3ETIAX.mjs +6 -0
- package/package.json +100 -0
package/dist/index.d.ts
ADDED
|
@@ -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 };
|