@testerpaykit/api-client 1.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,1117 @@
1
+ import axios, { AxiosInstance } from 'axios';
2
+ import {
3
+ IApiClient,
4
+ LoginRequest,
5
+ LoginResponse,
6
+ WeeklySummary,
7
+ TokenManager,
8
+ VoiceBugExtractResponse,
9
+ } from '@testerpaykit/core';
10
+
11
+ export interface ApiClientConfig {
12
+ baseURL?: string;
13
+ apiKey: string;
14
+ tokenManager?: TokenManager;
15
+ }
16
+
17
+ /**
18
+ * TesterPayKit API Client implementation using Axios.
19
+ *
20
+ * Features:
21
+ * - JWT token authentication with automatic refresh
22
+ * - Request/response interceptors for auth headers
23
+ * - Integration with TokenManager for token lifecycle
24
+ */
25
+ export class TesterPayKitApiClient implements IApiClient {
26
+ private client: AxiosInstance;
27
+ private tokenManager: TokenManager;
28
+ private apiKey: string;
29
+
30
+ constructor(config: ApiClientConfig) {
31
+ this.apiKey = config.apiKey;
32
+ this.tokenManager = config.tokenManager || new TokenManager();
33
+
34
+ this.client = axios.create({
35
+ baseURL: config.baseURL || 'https://api.testerpaykit.com',
36
+ headers: {
37
+ 'Content-Type': 'application/json',
38
+ 'X-API-Key': this.apiKey,
39
+ },
40
+ });
41
+
42
+ this.setupInterceptors();
43
+ }
44
+
45
+ /**
46
+ * Setup request/response interceptors for JWT authentication.
47
+ */
48
+ private setupInterceptors(): void {
49
+ // Request interceptor: Add auth token to every request
50
+ this.client.interceptors.request.use(async (config) => {
51
+ const token = await this.tokenManager.ensureValidToken();
52
+ if (token) {
53
+ config.headers.Authorization = `Bearer ${token}`;
54
+ }
55
+ return config;
56
+ });
57
+
58
+ // Response interceptor: Handle 401 errors (token expired)
59
+ this.client.interceptors.response.use(
60
+ (response) => response,
61
+ async (error) => {
62
+ if (error.response?.status === 401) {
63
+ // Token expired or invalid, clear tokens
64
+ this.tokenManager.clear();
65
+ }
66
+ return Promise.reject(error);
67
+ }
68
+ );
69
+ }
70
+
71
+ /**
72
+ * Authenticate a tester with email/password.
73
+ * Stores tokens in TokenManager and sets up refresh callback.
74
+ */
75
+ async login(request: LoginRequest): Promise<LoginResponse> {
76
+ const response = await this.client.post<LoginResponse>('/auth/login', request);
77
+
78
+ if (response.data.accessToken && response.data.refreshToken) {
79
+ this.tokenManager.setTokens(response.data.accessToken, response.data.refreshToken);
80
+ this.tokenManager.setRefreshCallback(async (refreshToken) => {
81
+ const refreshResponse = await this.refreshToken(refreshToken);
82
+ return refreshResponse.accessToken!;
83
+ });
84
+ }
85
+
86
+ return response.data;
87
+ }
88
+
89
+ /**
90
+ * Refresh access token using refresh token.
91
+ * Updates TokenManager with new access token.
92
+ */
93
+ async refreshToken(refreshToken: string): Promise<LoginResponse> {
94
+ const response = await this.client.post<LoginResponse>('/v1/auth/refresh', {
95
+ refreshToken,
96
+ });
97
+
98
+ if (response.data.accessToken) {
99
+ this.tokenManager.setTokens(response.data.accessToken, refreshToken);
100
+ }
101
+
102
+ return response.data;
103
+ }
104
+
105
+ /**
106
+ * Submit a weekly summary for payment.
107
+ * POST /v1/submissions
108
+ */
109
+ async submitSummary(summary: WeeklySummary): Promise<SubmissionResponse> {
110
+ const response = await this.client.post<SubmissionResponse>(
111
+ '/v1/submissions',
112
+ summary
113
+ );
114
+ return response.data;
115
+ }
116
+
117
+ /**
118
+ * Get submissions for the authenticated tester.
119
+ * GET /v1/submissions
120
+ */
121
+ async getPendingSubmissions(params?: {
122
+ status?: string;
123
+ limit?: number;
124
+ offset?: number;
125
+ }): Promise<WeeklySummary[]> {
126
+ const response = await this.client.get<WeeklySummary[]>('/v1/submissions', { params });
127
+ return response.data;
128
+ }
129
+
130
+ /**
131
+ * Fetch the set of submission IDs the server already holds.
132
+ * GET /v1/submissions?limit=100
133
+ * Soft-fail: returns empty set on any error.
134
+ */
135
+ async fetchServerSubmissionIds(): Promise<Set<string>> {
136
+ try {
137
+ const submissions = await this.getPendingSubmissions({ limit: 100 });
138
+ return new Set(submissions.map((s) => s.id));
139
+ } catch {
140
+ return new Set();
141
+ }
142
+ }
143
+
144
+ /**
145
+ * Set access token manually (for testing or external auth flows).
146
+ */
147
+ setAccessToken(token: string): void {
148
+ this.tokenManager.setTokens(token, '');
149
+ }
150
+
151
+ /**
152
+ * Acquire an anonymous tester JWT by trading a {projectId, code}
153
+ * pair for an access + refresh token. No email/password required.
154
+ *
155
+ * Server-side this hits POST /auth/tester/anonymous; a synthetic
156
+ * email derived from {projectId, code} is the dedup key so the
157
+ * same code resolves to the same tester row every time.
158
+ */
159
+ async loginAnonymous(
160
+ projectId: string,
161
+ code: string,
162
+ ): Promise<AnonymousLoginResponse & { testerId?: string }> {
163
+ const response = await this.client.post<AnonymousLoginResponse>(
164
+ '/auth/tester/anonymous',
165
+ { projectId, code },
166
+ );
167
+ if (response.data.accessToken) {
168
+ this.tokenManager.setTokens(
169
+ response.data.accessToken,
170
+ response.data.refreshToken,
171
+ );
172
+ }
173
+ return { ...response.data, testerId: response.data.tester?.id };
174
+ }
175
+
176
+ /**
177
+ * Request a passwordless magic-link sign-in for a tester (or coordinator).
178
+ * POST /auth/magic-link/request. The server emails a single-use link; when
179
+ * `returnUrl` is a first-party *.moinsen.dev origin the link returns there
180
+ * with the token, otherwise it points at the console. `country` (DE/AT/CH)
181
+ * enables open tester self-signup for unknown emails. Always resolves; the
182
+ * response is intentionally generic (no user enumeration).
183
+ */
184
+ async requestMagicLink(input: {
185
+ email: string;
186
+ returnUrl?: string;
187
+ country?: string;
188
+ then?: string;
189
+ }): Promise<{ ok?: boolean; message?: string }> {
190
+ const response = await this.client.post('/auth/magic-link/request', {
191
+ email: input.email,
192
+ ...(input.returnUrl && { returnUrl: input.returnUrl }),
193
+ ...(input.country && { country: input.country }),
194
+ ...(input.then && { then: input.then }),
195
+ });
196
+ return response.data as { ok?: boolean; message?: string };
197
+ }
198
+
199
+ /**
200
+ * Consume a magic-link token (from the returned URL). POST
201
+ * /auth/magic-link/consume. On success stores the minted JWTs and returns
202
+ * the tester/coordinator payload.
203
+ */
204
+ async consumeMagicLink(token: string): Promise<{
205
+ accessToken: string;
206
+ refreshToken?: string;
207
+ userType?: string;
208
+ tester?: { id: string; email: string; displayName?: string; status?: string };
209
+ }> {
210
+ const response = await this.client.post('/auth/magic-link/consume', { token });
211
+ const data = response.data as {
212
+ accessToken: string;
213
+ refreshToken?: string;
214
+ userType?: string;
215
+ tester?: { id: string; email: string; displayName?: string; status?: string };
216
+ };
217
+ if (data.accessToken) {
218
+ this.tokenManager.setTokens(data.accessToken, data.refreshToken ?? '');
219
+ }
220
+ return data;
221
+ }
222
+
223
+ /**
224
+ * Submit a bug report to the server. Hits
225
+ * POST /v1/testers/me/bug-reports with the tester JWT already
226
+ * attached by the request interceptor (call loginAnonymous /
227
+ * loginCoordinator first).
228
+ *
229
+ * Server-side enum constraints are enforced — see the typedef
230
+ * for valid {type, severity, category} values. Sending an
231
+ * out-of-band string returns 500 with a detail message in
232
+ * development mode.
233
+ */
234
+ async submitBugReport(
235
+ // Record<string, any> (not unknown) so the param matches IApiClient AND still
236
+ // accepts interface-typed payloads like BugReportPayload — `Record<string,
237
+ // unknown>` rejects interfaces (no implicit index signature). BugReportPayload
238
+ // (exported below) documents the expected field shape for callers.
239
+ payload: Record<string, any>,
240
+ options?: { idempotencyKey?: string },
241
+ ): Promise<BugReportResponse> {
242
+ // Client-supplied idempotency key (UUIDv4 minted once per submit
243
+ // attempt). The server stores it in bug_reports.idempotency_key
244
+ // with a partial unique index — second POST with the same key
245
+ // returns the existing row id + `deduplicated: true` instead of
246
+ // inserting a duplicate. See migration 027 for context. Optional
247
+ // for backward compat with older SDKs that don't generate keys.
248
+ const headers: Record<string, string> = {};
249
+ if (options?.idempotencyKey) {
250
+ headers['X-Idempotency-Key'] = options.idempotencyKey;
251
+ }
252
+ const response = await this.client.post<BugReportResponse>(
253
+ '/v1/testers/me/bug-reports',
254
+ payload,
255
+ Object.keys(headers).length ? { headers } : undefined,
256
+ );
257
+ return response.data;
258
+ }
259
+
260
+ /**
261
+ * List the bug reports this tester submitted (newest first), with their
262
+ * current status. Hits GET /v1/testers/me/bug-reports. Mirrors the
263
+ * Flutter SDK's getMyBugReports — powers the "Meine Bugs" screen.
264
+ */
265
+ async listMyBugReports(params?: {
266
+ status?: string;
267
+ limit?: number;
268
+ page?: number;
269
+ }): Promise<MyBugReportsResponse> {
270
+ const response = await this.client.get<MyBugReportsResponse>(
271
+ '/v1/testers/me/bug-reports',
272
+ { params },
273
+ );
274
+ return response.data;
275
+ }
276
+
277
+ /**
278
+ * The tester's in-app notifications (newest first) + the unread count.
279
+ * GET /v1/testers/me/notifications. Mirrors the Flutter SDK's
280
+ * getMyNotifications — powers the "Nachrichten" inbox.
281
+ */
282
+ async getMyNotifications(params?: {
283
+ limit?: number;
284
+ unreadOnly?: boolean;
285
+ }): Promise<NotificationsResult> {
286
+ const response = await this.client.get<NotificationsResult>(
287
+ '/v1/testers/me/notifications',
288
+ { params },
289
+ );
290
+ return response.data;
291
+ }
292
+
293
+ /**
294
+ * Mark notifications read. Pass an `id` to mark one, or omit to mark all.
295
+ * POST /v1/testers/me/notifications/read. Returns the new unread count.
296
+ */
297
+ async markNotificationsRead(params?: { id?: string }): Promise<number> {
298
+ const response = await this.client.post<{
299
+ ok: boolean;
300
+ unreadCount: number;
301
+ }>(
302
+ '/v1/testers/me/notifications/read',
303
+ params?.id ? { id: params.id } : {},
304
+ );
305
+ return response.data.unreadCount;
306
+ }
307
+
308
+ /**
309
+ * Attach a file (screenshot, log, voice note) to an already-
310
+ * submitted bug report. Hits POST /v1/testers/me/bug-reports/
311
+ * [id]/attachments. Base64-encoded payload, server stores blob
312
+ * + returns metadata.
313
+ */
314
+ async attachToBugReport(
315
+ bugReportId: string,
316
+ attachment: BugReportAttachmentInput,
317
+ ): Promise<BugReportAttachmentResponse> {
318
+ const response = await this.client.post<BugReportAttachmentResponse>(
319
+ `/v1/testers/me/bug-reports/${bugReportId}/attachments`,
320
+ attachment,
321
+ );
322
+ return response.data;
323
+ }
324
+
325
+ /**
326
+ * Start a server-side tester session. The API uses snake_case
327
+ * field names here because this maps directly to the sessions
328
+ * table and existing Flutter SDK contract.
329
+ */
330
+ async startTesterSession(
331
+ input: StartTesterSessionInput,
332
+ ): Promise<TesterSessionResponse> {
333
+ const body = {
334
+ project_id: input.projectId,
335
+ ...(input.deviceInfo && { device_info: input.deviceInfo }),
336
+ ...(input.appVersion && { app_version: input.appVersion }),
337
+ ...(input.sdkVersion && { sdk_version: input.sdkVersion }),
338
+ ...(input.deviceId && { device_id: input.deviceId }),
339
+ };
340
+ const response = await this.client.post<{
341
+ session: TesterSessionResponse;
342
+ }>('/v1/testers/sessions', body);
343
+ return response.data.session;
344
+ }
345
+
346
+ /** End a server-side tester session with optional counters. */
347
+ async endTesterSession(input: EndTesterSessionInput): Promise<void> {
348
+ await this.client.put(`/v1/testers/sessions/${input.sessionId}`, {
349
+ ended_at: (input.endedAt ?? new Date()).toISOString(),
350
+ ...(input.bugsFound != null && { bugs_found: input.bugsFound }),
351
+ ...(input.tasksCompleted != null && {
352
+ tasks_completed: input.tasksCompleted,
353
+ }),
354
+ ...(input.endReason && { end_reason: input.endReason }),
355
+ ...(input.foregroundSeconds != null && {
356
+ foreground_seconds: input.foregroundSeconds,
357
+ }),
358
+ });
359
+ }
360
+
361
+ /**
362
+ * Add one or more timeline events to an active tester session.
363
+ * Hits POST /v1/testers/sessions/:id/events in batch mode.
364
+ */
365
+ async addSessionEvents(
366
+ sessionId: string,
367
+ events: SessionEventInput[],
368
+ ): Promise<SessionEventsResponse> {
369
+ const response = await this.client.post<SessionEventsResponse>(
370
+ `/v1/testers/sessions/${sessionId}/events`,
371
+ {
372
+ events: events.map((event) => ({
373
+ event_type: event.eventType,
374
+ ...(event.eventData && { event_data: event.eventData }),
375
+ ...(event.screenRoute && { screen_route: event.screenRoute }),
376
+ ...(event.timestamp && {
377
+ timestamp: formatTimestamp(event.timestamp),
378
+ }),
379
+ })),
380
+ },
381
+ );
382
+ return response.data;
383
+ }
384
+
385
+ /**
386
+ * Add one or more breadcrumbs to an active tester session.
387
+ * Hits POST /v1/testers/sessions/:id/breadcrumbs in batch mode.
388
+ */
389
+ async addSessionBreadcrumbs(
390
+ sessionId: string,
391
+ breadcrumbs: SessionBreadcrumbInput[],
392
+ ): Promise<SessionBreadcrumbsResponse> {
393
+ const response = await this.client.post<SessionBreadcrumbsResponse>(
394
+ `/v1/testers/sessions/${sessionId}/breadcrumbs`,
395
+ {
396
+ breadcrumbs: breadcrumbs.map((breadcrumb) => ({
397
+ breadcrumb_type: breadcrumb.breadcrumbType,
398
+ message: breadcrumb.message,
399
+ ...(breadcrumb.metadata && { metadata: breadcrumb.metadata }),
400
+ ...(breadcrumb.timestamp && {
401
+ timestamp: formatTimestamp(breadcrumb.timestamp),
402
+ }),
403
+ })),
404
+ },
405
+ );
406
+ return response.data;
407
+ }
408
+
409
+ /**
410
+ * Fetch the tester's assigned tasks. Server-side filter by
411
+ * status / project_id. Hits GET /v1/testers/tasks.
412
+ */
413
+ async getMyTasks(
414
+ filter: TaskListFilter = {},
415
+ ): Promise<TaskListResponse> {
416
+ const response = await this.client.get<TaskListResponse>(
417
+ '/v1/testers/tasks',
418
+ { params: filter },
419
+ );
420
+ return response.data;
421
+ }
422
+
423
+ /**
424
+ * Mark a task assignment in-progress. PUT /v1/testers/tasks/{id}/start.
425
+ * The server only completes an in-progress task, so callers start first.
426
+ */
427
+ async startTaskAssignment(assignmentId: string): Promise<void> {
428
+ await this.client.put(`/v1/testers/tasks/${assignmentId}/start`);
429
+ }
430
+
431
+ /** Complete a task assignment. PUT /v1/testers/tasks/{id}/complete. */
432
+ async completeTaskAssignment(assignmentId: string): Promise<void> {
433
+ await this.client.put(`/v1/testers/tasks/${assignmentId}/complete`);
434
+ }
435
+
436
+ /**
437
+ * Enroll the authenticated tester in a project. Idempotent —
438
+ * a second enroll on the same project resolves to the existing
439
+ * enrollment row. POST /v1/testers/projects/:id/enroll.
440
+ */
441
+ async enrollInProject(projectId: string): Promise<EnrollmentResponse> {
442
+ const response = await this.client.post<EnrollmentResponse>(
443
+ `/v1/testers/projects/${projectId}/enroll`,
444
+ );
445
+ return response.data;
446
+ }
447
+
448
+ /**
449
+ * Reverse of enrollInProject. POST /v1/testers/projects/:id/unenroll.
450
+ */
451
+ async unenrollFromProject(projectId: string): Promise<void> {
452
+ await this.client.post(`/v1/testers/projects/${projectId}/unenroll`);
453
+ }
454
+
455
+ /**
456
+ * Tester profile (handle, points, rating, etc.).
457
+ * GET /v1/testers/me/profile.
458
+ */
459
+ async getMyProfile(): Promise<TesterProfile> {
460
+ const response = await this.client.get<TesterProfile>(
461
+ '/v1/testers/me/profile',
462
+ );
463
+ return response.data;
464
+ }
465
+
466
+ /** GET /v1/testers/me/points — current point balance + breakdown. */
467
+ async getMyPoints(): Promise<TesterPoints> {
468
+ const response = await this.client.get<TesterPoints>(
469
+ '/v1/testers/me/points',
470
+ );
471
+ return response.data;
472
+ }
473
+
474
+ /** GET /v1/testers/earnings/summary — totals, current balance, this month. */
475
+ async getEarningsSummary(): Promise<EarningsSummary> {
476
+ const response = await this.client.get<EarningsSummary>(
477
+ '/v1/testers/earnings/summary',
478
+ );
479
+ return response.data;
480
+ }
481
+
482
+ /** GET /v1/testers/earnings/payouts — paginated payout history. */
483
+ async getMyPayouts(params?: { limit?: number; offset?: number }): Promise<{
484
+ payouts: PayoutRecord[];
485
+ total: number;
486
+ }> {
487
+ const response = await this.client.get<{
488
+ payouts: PayoutRecord[];
489
+ total: number;
490
+ }>('/v1/testers/earnings/payouts', { params });
491
+ return response.data;
492
+ }
493
+
494
+ /**
495
+ * GET /v1/testers/me/projects/:bundleIdOrUuid/knowledge-base
496
+ *
497
+ * Lists the markdown docs the coordinator attached to this project.
498
+ * Feeds the SDK widget's "ask a question about the project" flow.
499
+ * No content in the list response — call `getKnowledgeFile` for the
500
+ * full body. Accepts either the project's bundle id (what the host
501
+ * SDK already knows from its build) or its UUID.
502
+ */
503
+ async listKnowledgeFiles(
504
+ bundleIdOrProjectId: string,
505
+ ): Promise<{ projectId: string; files: KnowledgeFileSummary[] }> {
506
+ const projectSegment = encodeURIComponent(bundleIdOrProjectId);
507
+ const response = await this.client.get<{
508
+ projectId: string;
509
+ files: KnowledgeFileSummary[];
510
+ }>(
511
+ `/v1/testers/me/projects/${projectSegment}/knowledge-base`,
512
+ );
513
+ return response.data;
514
+ }
515
+
516
+ /**
517
+ * GET /v1/testers/me/projects/:bundleIdOrUuid/knowledge-base/:fileId
518
+ *
519
+ * Fetches one markdown doc's full content. Caller is expected to
520
+ * scope the fetch — passing the same `bundleIdOrProjectId` that
521
+ * `listKnowledgeFiles` was called with is the natural pattern.
522
+ */
523
+ async getKnowledgeFile(
524
+ bundleIdOrProjectId: string,
525
+ fileId: string,
526
+ ): Promise<KnowledgeFile> {
527
+ const projectSegment = encodeURIComponent(bundleIdOrProjectId);
528
+ const fileSegment = encodeURIComponent(fileId);
529
+ const response = await this.client.get<{ file: KnowledgeFile }>(
530
+ `/v1/testers/me/projects/${projectSegment}/knowledge-base/${fileSegment}`,
531
+ );
532
+ return response.data.file;
533
+ }
534
+
535
+ /**
536
+ * POST /v1/testers/me/projects/:bundleIdOrUuid/knowledge-base/query
537
+ *
538
+ * RAG over the project's knowledge-base markdown files. Embeds the
539
+ * question, retrieves top-K nearest chunks via pgvector cosine
540
+ * similarity, and asks gpt-4o-mini to synthesise an answer that
541
+ * STRICTLY cites those chunks. Answer language tracks the
542
+ * question (English / German).
543
+ *
544
+ * Returns {answer, citations}. The widget UI surfaces the answer
545
+ * + a "Sources" disclosure with the citations so the tester knows
546
+ * which doc the answer came from. `citations[*].content` is the
547
+ * exact span the model saw — ready to render as a snippet.
548
+ */
549
+ async askKnowledgeBase(
550
+ bundleIdOrProjectId: string,
551
+ question: string,
552
+ ): Promise<KnowledgeBaseAnswer> {
553
+ const projectSegment = encodeURIComponent(bundleIdOrProjectId);
554
+ const response = await this.client.post<KnowledgeBaseAnswer>(
555
+ `/v1/testers/me/projects/${projectSegment}/knowledge-base/query`,
556
+ { question },
557
+ );
558
+ return response.data;
559
+ }
560
+
561
+ /**
562
+ * GET /v1/tasks
563
+ * List available task presets for a project.
564
+ */
565
+ async getTasks(params?: { projectId?: string }): Promise<TaskPreset[]> {
566
+ const response = await this.client.get<TaskPreset[]>('/v1/tasks', { params });
567
+ return response.data;
568
+ }
569
+
570
+ /**
571
+ * POST /v1/testers/me/devices
572
+ * Register (or upsert) this device for push notifications.
573
+ * Server keys on device_token — a second POST with the same token updates the row.
574
+ */
575
+ async registerDevice(input: RegisterDeviceInput): Promise<TesterDeviceResponse> {
576
+ const body: Record<string, string> = {
577
+ device_token: input.deviceToken,
578
+ device_type: input.deviceType,
579
+ };
580
+ if (input.deviceModel) body.device_model = input.deviceModel;
581
+ if (input.osVersion) body.os_version = input.osVersion;
582
+ if (input.appVersion) body.app_version = input.appVersion;
583
+ const response = await this.client.post<TesterDeviceResponse>(
584
+ '/v1/testers/me/devices',
585
+ body,
586
+ );
587
+ return response.data;
588
+ }
589
+
590
+ /**
591
+ * POST /v1/session-feedback
592
+ * Submit end-of-session feedback (rating, comments, etc.).
593
+ */
594
+ async submitSessionEndFeedback(
595
+ payload: Record<string, unknown>,
596
+ ): Promise<FeedbackResponse> {
597
+ const response = await this.client.post<FeedbackResponse>(
598
+ '/v1/session-feedback',
599
+ payload,
600
+ );
601
+ return response.data;
602
+ }
603
+
604
+ /**
605
+ * Upload an attachment directly (not tied to a specific bug report).
606
+ * POST /v1/attachments — alternate path from the contract alongside
607
+ * /v1/testers/me/bug-reports/{id}/attachments.
608
+ */
609
+ async uploadAttachment(
610
+ attachment: BugReportAttachmentInput,
611
+ ): Promise<BugReportAttachmentResponse> {
612
+ const response = await this.client.post<BugReportAttachmentResponse>(
613
+ '/v1/attachments',
614
+ attachment,
615
+ );
616
+ return response.data;
617
+ }
618
+
619
+ /**
620
+ * GET /v1/testers/me/retests
621
+ * List bug reports assigned to this tester for re-verification.
622
+ */
623
+ async getMyRetests(params?: { status?: string }): Promise<RetestItem[]> {
624
+ const response = await this.client.get<RetestItem[]>(
625
+ '/v1/testers/me/retests',
626
+ { params },
627
+ );
628
+ return response.data;
629
+ }
630
+
631
+ /**
632
+ * POST /v1/testers/me/retests/{bugId}/verify
633
+ * Mark a retest as verified (bug is fixed).
634
+ */
635
+ async verifyRetest(bugId: string): Promise<void> {
636
+ await this.client.post(`/v1/testers/me/retests/${bugId}/verify`);
637
+ }
638
+
639
+ /**
640
+ * POST /v1/testers/me/retests/{bugId}/reopen
641
+ * Reopen a retest (bug is still present), optionally with a reason.
642
+ */
643
+ async reopenRetest(bugId: string, reason?: string): Promise<void> {
644
+ await this.client.post(`/v1/testers/me/retests/${bugId}/reopen`, {
645
+ ...(reason ? { reason } : {}),
646
+ });
647
+ }
648
+
649
+ /**
650
+ * POST /v1/testers/me/bug-reports/voice-extract
651
+ * Contract: wire.bug_reports.voiceExtractBugFields
652
+ *
653
+ * Sends base64-encoded audio to the server. The server runs Whisper
654
+ * (transcription) + gpt-4o-mini (structured extraction) and returns
655
+ * pre-filled bug-report fields in the tester's language.
656
+ *
657
+ * Wire body uses snake_case per contract. Timeout is 60 s because
658
+ * Whisper + Chat round-trip can take 10-30 s on long recordings.
659
+ */
660
+ async voiceExtractBugFields(request: {
661
+ audioBase64: string;
662
+ mimeType: string;
663
+ sourceLanguage?: string;
664
+ projectId?: string;
665
+ preClassification?: string;
666
+ }): Promise<VoiceBugExtractResponse> {
667
+ const body: Record<string, string> = {
668
+ audio_base64: request.audioBase64,
669
+ mime_type: request.mimeType,
670
+ };
671
+ if (request.sourceLanguage) body.source_language = request.sourceLanguage;
672
+ if (request.projectId) body.project_id = request.projectId;
673
+ if (request.preClassification) body.pre_classification = request.preClassification;
674
+
675
+ const response = await this.client.post<VoiceBugExtractResponse>(
676
+ '/v1/testers/me/bug-reports/voice-extract',
677
+ body,
678
+ { timeout: 60000 },
679
+ );
680
+ return response.data;
681
+ }
682
+ }
683
+
684
+ /**
685
+ * Result from `askKnowledgeBase`.
686
+ */
687
+ export interface KnowledgeBaseAnswer {
688
+ /** The model's synthesised answer, scoped to the citation spans. */
689
+ answer: string;
690
+ /** Top-K chunks the model was given. Ordered by similarity. */
691
+ citations: KnowledgeBaseCitation[];
692
+ /** Resolved project UUID — useful for telemetry / dedup. */
693
+ projectId: string;
694
+ /** Echo of the model used for the answer (e.g. "gpt-4o-mini"). */
695
+ model?: string;
696
+ }
697
+
698
+ export interface KnowledgeBaseCitation {
699
+ chunkId: string;
700
+ content: string;
701
+ /** Cosine distance — smaller = more similar. */
702
+ distance: number;
703
+ fileName: string;
704
+ fileId: string;
705
+ }
706
+
707
+ /**
708
+ * Knowledge-base file metadata. Listed without `content`; call
709
+ * `getKnowledgeFile` to fetch the markdown body.
710
+ */
711
+ export interface KnowledgeFileSummary {
712
+ id: string;
713
+ fileName: string;
714
+ byteLength: number;
715
+ description: string | null;
716
+ createdAt: string;
717
+ updatedAt: string;
718
+ }
719
+
720
+ export interface KnowledgeFile extends KnowledgeFileSummary {
721
+ /** UTF-8 markdown. Hard-capped server-side at 1 MB. */
722
+ content: string;
723
+ }
724
+
725
+ /** Response from POST /auth/tester/anonymous */
726
+ export interface AnonymousLoginResponse {
727
+ accessToken: string;
728
+ refreshToken: string;
729
+ userType: 'tester';
730
+ tester: {
731
+ id: string;
732
+ code: string;
733
+ projectId: string;
734
+ };
735
+ }
736
+
737
+ export type BugReportType =
738
+ | 'bug'
739
+ | 'crash'
740
+ | 'uiIssue'
741
+ | 'performance'
742
+ | 'featureRequest'
743
+ | 'generalFeedback';
744
+
745
+ export type BugSeverity = 'critical' | 'high' | 'medium' | 'low';
746
+
747
+ export type BugCategory =
748
+ | 'functional'
749
+ | 'ui'
750
+ | 'performance'
751
+ | 'security'
752
+ | 'compatibility'
753
+ | 'localization'
754
+ | 'accessibility';
755
+
756
+ /**
757
+ * Summary of a bug report this tester submitted, as returned by
758
+ * GET /v1/testers/me/bug-reports. Powers the "Meine Bugs" screen.
759
+ */
760
+ export interface MyBugReportSummary {
761
+ id: string;
762
+ title: string;
763
+ description?: string | null;
764
+ status: string;
765
+ severity?: string | null;
766
+ createdAt: string;
767
+ }
768
+
769
+ export interface MyBugReportsResponse {
770
+ bugReports: MyBugReportSummary[];
771
+ pagination?: {
772
+ page: number;
773
+ limit: number;
774
+ totalCount: number;
775
+ totalPages: number;
776
+ hasNext: boolean;
777
+ hasPrev: boolean;
778
+ };
779
+ }
780
+
781
+ /**
782
+ * A tester-facing notification (bug accepted/fixed/rejected, retest assigned,
783
+ * reward). Returned by GET /v1/testers/me/notifications.
784
+ */
785
+ export interface TpkNotification {
786
+ id: string;
787
+ type: string;
788
+ title: string;
789
+ body?: string | null;
790
+ data?: Record<string, unknown>;
791
+ relatedBugId?: string | null;
792
+ isRead: boolean;
793
+ readAt?: string | null;
794
+ createdAt: string;
795
+ }
796
+
797
+ export interface NotificationsResult {
798
+ notifications: TpkNotification[];
799
+ unreadCount: number;
800
+ }
801
+
802
+ /** Bug-report payload accepted by POST /v1/testers/me/bug-reports. */
803
+ export interface BugReportPayload {
804
+ sessionId: string;
805
+ projectId: string;
806
+ type: BugReportType;
807
+ severity: BugSeverity;
808
+ category: BugCategory;
809
+ title: string;
810
+ description: string;
811
+ currentScreen: string;
812
+ deviceSnapshot: Record<string, unknown>;
813
+ appSnapshot: Record<string, unknown>;
814
+ // Optional
815
+ reproductionSteps?: unknown[];
816
+ expectedBehavior?: string;
817
+ actualBehavior?: string;
818
+ breadcrumbs?: unknown[];
819
+ affectedFeature?: string;
820
+ frequency?: 'always' | 'often' | 'sometimes' | 'rarely';
821
+ /**
822
+ * Voice-bug split (A2): when `transcript` is set the report is
823
+ * voice-originated — the server treats title/description as the
824
+ * tester's approved O-Ton (their language), stores them verbatim
825
+ * in bug_reports.tester_*, and derives the English enriched
826
+ * canonical title/description/expected/actual. `sourceLanguage` is
827
+ * the ISO-639-1 code the tester spoke. Absent for typed reports.
828
+ */
829
+ transcript?: string;
830
+ sourceLanguage?: string;
831
+ }
832
+
833
+ export interface BugReportResponse {
834
+ id: string;
835
+ status: string;
836
+ createdAt: string;
837
+ submittedAt: string;
838
+ message?: string;
839
+ /**
840
+ * True when the server matched an existing bug_reports row by the
841
+ * client-supplied `X-Idempotency-Key` rather than inserting a new
842
+ * one. Lets the SDK tell "fresh submission" from "your retry won
843
+ * the race" without parsing status codes. Always present in
844
+ * server responses since migration 027; older API versions omit it
845
+ * and it stays undefined.
846
+ */
847
+ deduplicated?: boolean;
848
+ }
849
+
850
+ /** Attachment upload input for an existing bug report. */
851
+ export interface BugReportAttachmentInput {
852
+ fileName: string;
853
+ fileType:
854
+ | 'image'
855
+ | 'screenshot'
856
+ | 'voice_note'
857
+ | 'screen_recording'
858
+ | 'video'
859
+ | 'audio'
860
+ | 'log'
861
+ | 'other';
862
+ fileSize: number;
863
+ /** Base64-encoded file contents. Required when filePath is absent. */
864
+ fileData?: string;
865
+ /** Server-side file reference (instead of fileData). */
866
+ filePath?: string;
867
+ mimeType?: string;
868
+ }
869
+
870
+ export interface StartTesterSessionInput {
871
+ projectId: string;
872
+ deviceInfo?: Record<string, unknown>;
873
+ appVersion?: string;
874
+ sdkVersion?: string;
875
+ deviceId?: string;
876
+ }
877
+
878
+ export interface TesterSessionResponse {
879
+ id: string;
880
+ project_id: string;
881
+ tester_id?: string;
882
+ started_at?: string;
883
+ ended_at?: string | null;
884
+ }
885
+
886
+ export type TesterSessionEndReason =
887
+ | 'completed'
888
+ | 'lifecycle_flush'
889
+ | 'timeout'
890
+ | 'abandoned';
891
+
892
+ export interface EndTesterSessionInput {
893
+ sessionId: string;
894
+ endedAt?: Date;
895
+ bugsFound?: number;
896
+ tasksCompleted?: number;
897
+ endReason?: TesterSessionEndReason;
898
+ foregroundSeconds?: number;
899
+ }
900
+
901
+ export interface SessionEventInput {
902
+ eventType: string;
903
+ eventData?: Record<string, unknown>;
904
+ screenRoute?: string;
905
+ timestamp?: Date | string;
906
+ }
907
+
908
+ export interface SessionEventsResponse {
909
+ inserted: number;
910
+ events: Array<{
911
+ id: string;
912
+ timestamp: string;
913
+ }>;
914
+ }
915
+
916
+ export interface SessionBreadcrumbInput {
917
+ breadcrumbType: string;
918
+ message: string;
919
+ metadata?: Record<string, unknown>;
920
+ timestamp?: Date | string;
921
+ }
922
+
923
+ export interface SessionBreadcrumbsResponse {
924
+ inserted: number;
925
+ breadcrumbs: Array<{
926
+ id: string;
927
+ timestamp: string;
928
+ }>;
929
+ }
930
+
931
+ export interface BugReportAttachmentResponse {
932
+ id: string;
933
+ fileName: string;
934
+ fileType: string;
935
+ fileSize: number;
936
+ uploadedAt: string;
937
+ }
938
+
939
+ export interface TaskListFilter {
940
+ status?: 'pending' | 'in_progress' | 'completed';
941
+ project_id?: string;
942
+ }
943
+
944
+ export interface TesterTask {
945
+ assignmentId: string;
946
+ taskPresetId: string;
947
+ status: 'pending' | 'in_progress' | 'completed';
948
+ assignedAt: string;
949
+ startedAt?: string | null;
950
+ completedAt?: string | null;
951
+ task: {
952
+ id: string;
953
+ name: string;
954
+ description: string | null;
955
+ rewardAmount: number | null;
956
+ estimatedDuration: number | null;
957
+ priority: string | null;
958
+ steps: unknown[];
959
+ relatedBugId?: string | null;
960
+ focusArea?: string | null;
961
+ };
962
+ project: {
963
+ id: string;
964
+ name: string;
965
+ bundleId: string;
966
+ };
967
+ build?: {
968
+ id: string;
969
+ version: string;
970
+ buildNumber: string;
971
+ } | null;
972
+ }
973
+
974
+ export interface TaskListResponse {
975
+ tasks: TesterTask[];
976
+ total: number;
977
+ summary: {
978
+ pending: number;
979
+ inProgress: number;
980
+ completed: number;
981
+ };
982
+ }
983
+
984
+ export interface EnrollmentResponse {
985
+ enrollmentId: string;
986
+ testerId: string;
987
+ projectId: string;
988
+ status: string;
989
+ enrolledAt: string;
990
+ }
991
+
992
+ export interface TesterProfile {
993
+ id: string;
994
+ email?: string | null;
995
+ handle?: string | null;
996
+ fullName?: string | null;
997
+ rating?: number | null;
998
+ pointsTotal?: number | null;
999
+ status?: string;
1000
+ createdAt?: string;
1001
+ }
1002
+
1003
+ export interface TesterPoints {
1004
+ total: number;
1005
+ breakdown?: Record<string, number>;
1006
+ }
1007
+
1008
+ /** Response from GET /v1/testers/earnings/summary. */
1009
+ export interface EarningsSummary {
1010
+ currentBalance: number;
1011
+ totalEarnings: {
1012
+ approved: number;
1013
+ pending: number;
1014
+ rejected: number;
1015
+ };
1016
+ submissions: {
1017
+ pending: number;
1018
+ approved: number;
1019
+ rejected: number;
1020
+ };
1021
+ payouts: {
1022
+ totalPaid: number;
1023
+ count: number;
1024
+ lastPayoutDate: string | null;
1025
+ };
1026
+ thisMonth: {
1027
+ submissions: number;
1028
+ earnings: number;
1029
+ };
1030
+ }
1031
+
1032
+ export interface PayoutRecord {
1033
+ id: string;
1034
+ amount: number;
1035
+ currency: string;
1036
+ status: 'pending' | 'processing' | 'completed' | 'failed';
1037
+ method?: string | null;
1038
+ createdAt: string;
1039
+ completedAt?: string | null;
1040
+ }
1041
+
1042
+ /** Response from POST /v1/submissions */
1043
+ export interface SubmissionResponse {
1044
+ id: string;
1045
+ status: string;
1046
+ message?: string;
1047
+ }
1048
+
1049
+ /** Input for POST /v1/testers/me/devices */
1050
+ export interface RegisterDeviceInput {
1051
+ deviceToken: string;
1052
+ deviceType: string;
1053
+ deviceModel?: string;
1054
+ osVersion?: string;
1055
+ appVersion?: string;
1056
+ }
1057
+
1058
+ /** Response from POST /v1/testers/me/devices */
1059
+ export interface TesterDeviceResponse {
1060
+ id: string;
1061
+ deviceToken: string;
1062
+ deviceType: string;
1063
+ }
1064
+
1065
+ /** Response from POST /v1/session-feedback */
1066
+ export interface FeedbackResponse {
1067
+ id: string;
1068
+ status: string;
1069
+ message?: string;
1070
+ }
1071
+
1072
+ /** A single retest item from GET /v1/testers/me/retests */
1073
+ export interface RetestItem {
1074
+ id: string;
1075
+ title: string;
1076
+ description?: string | null;
1077
+ expectedBehavior?: string | null;
1078
+ actualBehavior?: string | null;
1079
+ reproductionSteps?: unknown[] | null;
1080
+ fixedInVersion?: string | null;
1081
+ status: string;
1082
+ severity?: string | null;
1083
+ type?: string | null;
1084
+ retestAssignedAt?: string | null;
1085
+ createdAt: string;
1086
+ projectId: string;
1087
+ screenshotPath?: string | null;
1088
+ }
1089
+
1090
+ /** A task preset from GET /v1/tasks */
1091
+ export interface TaskPreset {
1092
+ id: string;
1093
+ projectId: string;
1094
+ title: string;
1095
+ description: string;
1096
+ steps: TaskStep[];
1097
+ isActive: boolean;
1098
+ createdAt: string;
1099
+ updatedAt: string;
1100
+ releaseId?: string | null;
1101
+ targetTesters?: number | null;
1102
+ payoutRuleId?: string | null;
1103
+ startsAt?: string | null;
1104
+ endsAt?: string | null;
1105
+ }
1106
+
1107
+ export interface TaskStep {
1108
+ order: number;
1109
+ title: string;
1110
+ description?: string | null;
1111
+ required: boolean;
1112
+ estimatedMinutes?: number | null;
1113
+ }
1114
+
1115
+ function formatTimestamp(timestamp: Date | string): string {
1116
+ return timestamp instanceof Date ? timestamp.toISOString() : timestamp;
1117
+ }