@testerpaykit/api-client 1.5.0 → 1.7.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/CHANGELOG.md ADDED
@@ -0,0 +1,27 @@
1
+ # Changelog
2
+
3
+ All notable changes to `@testerpaykit/api-client` are documented here.
4
+
5
+ ## 1.7.0 — 2026-11-01
6
+
7
+ ### Added
8
+ - `getChecklist(projectId)` — what to test in an app: the project's
9
+ checklist tasks with their steps and the tester's (`mine`) and the AI
10
+ tester's (`ai`) latest pass (`GET /v1/testers/me/checklist`). A 404
11
+ (tester not in the project yet) yields an empty list.
12
+ - `submitChecklistRun({projectId, taskId, stepResults, summary?})` — one
13
+ pass through a task with a verdict per step (`POST
14
+ /v1/testers/me/checklist/<taskId>/runs`), returns `passed`, `failed` or
15
+ `incomplete`.
16
+ - Types `ChecklistTask`, `ChecklistRun`, `ChecklistStepResult`,
17
+ `ChecklistRunInput`.
18
+
19
+ ### Changed
20
+ - `claimRemoteAiSession(projectId, appVersion?)` sends the app version, so
21
+ the API can hand AI retests of a fixed bug only to the fixed build.
22
+
23
+ ## 1.6.0 — 2026-10-31
24
+
25
+ ### Added
26
+ - `openLiveLink(projectId)` and `sendLiveNote(...)` for the live link to
27
+ Claude Code.
package/dist/index.d.mts CHANGED
@@ -1,5 +1,46 @@
1
1
  import { TokenManager, IApiClient, LoginRequest, LoginResponse, WeeklySummary, RemoteAiSession, VoiceBugExtractResponse, QuickActionKind } from '@testerpaykit/core';
2
2
 
3
+ /** Body of a "Send to Claude" note (see `sendLiveNote`). */
4
+ interface LiveNoteInput {
5
+ projectId: string;
6
+ text: string;
7
+ /** Screen snapshot without the screenshot (that goes separately). */
8
+ snapshot: Record<string, unknown>;
9
+ /** Base64 PNG/JPEG, no data-URI prefix. */
10
+ screenshotBase64?: string | null;
11
+ }
12
+ /** One step verdict of a checklist pass (`step` is 1-based). */
13
+ interface ChecklistStepResult {
14
+ step: number;
15
+ passed: boolean;
16
+ note?: string;
17
+ }
18
+ /** The latest pass through a checklist task (by this tester or the AI). */
19
+ interface ChecklistRun {
20
+ status: 'passed' | 'failed' | 'incomplete' | string;
21
+ steps: ChecklistStepResult[];
22
+ summary?: string;
23
+ at: string;
24
+ tester?: string;
25
+ }
26
+ /** One task of a project's checklist: what should be tested. */
27
+ interface ChecklistTask {
28
+ id: string;
29
+ title: string;
30
+ description?: string;
31
+ steps: string[];
32
+ /** This tester's latest pass. */
33
+ mine?: ChecklistRun;
34
+ /** The AI tester's latest pass. */
35
+ ai?: ChecklistRun;
36
+ }
37
+ /** Body of `submitChecklistRun`. */
38
+ interface ChecklistRunInput {
39
+ projectId: string;
40
+ taskId: string;
41
+ stepResults: ChecklistStepResult[];
42
+ summary?: string;
43
+ }
3
44
  interface ApiClientConfig {
4
45
  baseURL?: string;
5
46
  apiKey: string;
@@ -143,8 +184,33 @@ declare class TesterPayKitApiClient implements IApiClient {
143
184
  /**
144
185
  * Claim a remote AI-tester run waiting for this project.
145
186
  * POST /v1/testers/me/ai-sessions/claim — 204 → null.
187
+ * `appVersion` lets the API hand out AI retests of a fixed bug, which
188
+ * only a build at or above the fixed version may run.
189
+ */
190
+ claimRemoteAiSession(projectId: string, appVersion?: string): Promise<RemoteAiSession | null>;
191
+ /**
192
+ * Open a live link to the developer's Claude Code session: returns a
193
+ * one-time WebSocket URL (valid two minutes). Fetch a fresh one for
194
+ * every (re)connect. POST /v1/testers/me/live.
195
+ */
196
+ openLiveLink(projectId: string): Promise<string>;
197
+ /**
198
+ * "Send to Claude": one line plus what the screen showed. Works
199
+ * without an open live link. POST /v1/testers/me/live/notes → note id.
200
+ */
201
+ sendLiveNote(input: LiveNoteInput): Promise<string>;
202
+ /**
203
+ * What to test in this app: the project's checklist tasks with this
204
+ * tester's (`mine`) and the AI tester's (`ai`) latest pass.
205
+ * GET /v1/testers/me/checklist?project_id=… — a 404 (tester not in the
206
+ * project yet) yields an empty list.
207
+ */
208
+ getChecklist(projectId: string): Promise<ChecklistTask[]>;
209
+ /**
210
+ * One pass through a checklist task, a verdict per step.
211
+ * POST /v1/testers/me/checklist/{taskId}/runs → the run's status.
146
212
  */
147
- claimRemoteAiSession(projectId: string): Promise<RemoteAiSession | null>;
213
+ submitChecklistRun(input: ChecklistRunInput): Promise<string>;
148
214
  /**
149
215
  * Attach a file (screenshot, log, voice note) to an already-
150
216
  * submitted bug report. Hits POST /v1/testers/me/bug-reports/
@@ -719,4 +785,4 @@ interface TaskStep {
719
785
  }
720
786
 
721
787
  export { TesterPayKitApiClient };
722
- export type { AnonymousLoginResponse, ApiClientConfig, BugCategory, BugReportAttachmentInput, BugReportAttachmentResponse, BugReportPayload, BugReportResponse, BugReportType, BugSeverity, EarningsSummary, EndTesterSessionInput, EnrollmentResponse, FeedbackResponse, KnowledgeBaseAnswer, KnowledgeBaseCitation, KnowledgeFile, KnowledgeFileSummary, MyBugReportSummary, MyBugReportsResponse, NotificationsResult, PayoutRecord, RegisterDeviceInput, RetestItem, RetestStepVerdicts, SdkUpdateInfo, SessionBreadcrumbInput, SessionBreadcrumbsResponse, SessionEventInput, SessionEventsResponse, StartTesterSessionInput, SubmissionResponse, TaskListFilter, TaskListResponse, TaskPreset, TaskStep, TesterDeviceResponse, TesterPoints, TesterProfile, TesterSessionEndReason, TesterSessionResponse, TesterTask, TpkNotification };
788
+ export type { AnonymousLoginResponse, ApiClientConfig, BugCategory, BugReportAttachmentInput, BugReportAttachmentResponse, BugReportPayload, BugReportResponse, BugReportType, BugSeverity, ChecklistRun, ChecklistRunInput, ChecklistStepResult, ChecklistTask, EarningsSummary, EndTesterSessionInput, EnrollmentResponse, FeedbackResponse, KnowledgeBaseAnswer, KnowledgeBaseCitation, KnowledgeFile, KnowledgeFileSummary, LiveNoteInput, MyBugReportSummary, MyBugReportsResponse, NotificationsResult, PayoutRecord, RegisterDeviceInput, RetestItem, RetestStepVerdicts, SdkUpdateInfo, SessionBreadcrumbInput, SessionBreadcrumbsResponse, SessionEventInput, SessionEventsResponse, StartTesterSessionInput, SubmissionResponse, TaskListFilter, TaskListResponse, TaskPreset, TaskStep, TesterDeviceResponse, TesterPoints, TesterProfile, TesterSessionEndReason, TesterSessionResponse, TesterTask, TpkNotification };
package/dist/index.d.ts CHANGED
@@ -1,5 +1,46 @@
1
1
  import { TokenManager, IApiClient, LoginRequest, LoginResponse, WeeklySummary, RemoteAiSession, VoiceBugExtractResponse, QuickActionKind } from '@testerpaykit/core';
2
2
 
3
+ /** Body of a "Send to Claude" note (see `sendLiveNote`). */
4
+ interface LiveNoteInput {
5
+ projectId: string;
6
+ text: string;
7
+ /** Screen snapshot without the screenshot (that goes separately). */
8
+ snapshot: Record<string, unknown>;
9
+ /** Base64 PNG/JPEG, no data-URI prefix. */
10
+ screenshotBase64?: string | null;
11
+ }
12
+ /** One step verdict of a checklist pass (`step` is 1-based). */
13
+ interface ChecklistStepResult {
14
+ step: number;
15
+ passed: boolean;
16
+ note?: string;
17
+ }
18
+ /** The latest pass through a checklist task (by this tester or the AI). */
19
+ interface ChecklistRun {
20
+ status: 'passed' | 'failed' | 'incomplete' | string;
21
+ steps: ChecklistStepResult[];
22
+ summary?: string;
23
+ at: string;
24
+ tester?: string;
25
+ }
26
+ /** One task of a project's checklist: what should be tested. */
27
+ interface ChecklistTask {
28
+ id: string;
29
+ title: string;
30
+ description?: string;
31
+ steps: string[];
32
+ /** This tester's latest pass. */
33
+ mine?: ChecklistRun;
34
+ /** The AI tester's latest pass. */
35
+ ai?: ChecklistRun;
36
+ }
37
+ /** Body of `submitChecklistRun`. */
38
+ interface ChecklistRunInput {
39
+ projectId: string;
40
+ taskId: string;
41
+ stepResults: ChecklistStepResult[];
42
+ summary?: string;
43
+ }
3
44
  interface ApiClientConfig {
4
45
  baseURL?: string;
5
46
  apiKey: string;
@@ -143,8 +184,33 @@ declare class TesterPayKitApiClient implements IApiClient {
143
184
  /**
144
185
  * Claim a remote AI-tester run waiting for this project.
145
186
  * POST /v1/testers/me/ai-sessions/claim — 204 → null.
187
+ * `appVersion` lets the API hand out AI retests of a fixed bug, which
188
+ * only a build at or above the fixed version may run.
189
+ */
190
+ claimRemoteAiSession(projectId: string, appVersion?: string): Promise<RemoteAiSession | null>;
191
+ /**
192
+ * Open a live link to the developer's Claude Code session: returns a
193
+ * one-time WebSocket URL (valid two minutes). Fetch a fresh one for
194
+ * every (re)connect. POST /v1/testers/me/live.
195
+ */
196
+ openLiveLink(projectId: string): Promise<string>;
197
+ /**
198
+ * "Send to Claude": one line plus what the screen showed. Works
199
+ * without an open live link. POST /v1/testers/me/live/notes → note id.
200
+ */
201
+ sendLiveNote(input: LiveNoteInput): Promise<string>;
202
+ /**
203
+ * What to test in this app: the project's checklist tasks with this
204
+ * tester's (`mine`) and the AI tester's (`ai`) latest pass.
205
+ * GET /v1/testers/me/checklist?project_id=… — a 404 (tester not in the
206
+ * project yet) yields an empty list.
207
+ */
208
+ getChecklist(projectId: string): Promise<ChecklistTask[]>;
209
+ /**
210
+ * One pass through a checklist task, a verdict per step.
211
+ * POST /v1/testers/me/checklist/{taskId}/runs → the run's status.
146
212
  */
147
- claimRemoteAiSession(projectId: string): Promise<RemoteAiSession | null>;
213
+ submitChecklistRun(input: ChecklistRunInput): Promise<string>;
148
214
  /**
149
215
  * Attach a file (screenshot, log, voice note) to an already-
150
216
  * submitted bug report. Hits POST /v1/testers/me/bug-reports/
@@ -719,4 +785,4 @@ interface TaskStep {
719
785
  }
720
786
 
721
787
  export { TesterPayKitApiClient };
722
- export type { AnonymousLoginResponse, ApiClientConfig, BugCategory, BugReportAttachmentInput, BugReportAttachmentResponse, BugReportPayload, BugReportResponse, BugReportType, BugSeverity, EarningsSummary, EndTesterSessionInput, EnrollmentResponse, FeedbackResponse, KnowledgeBaseAnswer, KnowledgeBaseCitation, KnowledgeFile, KnowledgeFileSummary, MyBugReportSummary, MyBugReportsResponse, NotificationsResult, PayoutRecord, RegisterDeviceInput, RetestItem, RetestStepVerdicts, SdkUpdateInfo, SessionBreadcrumbInput, SessionBreadcrumbsResponse, SessionEventInput, SessionEventsResponse, StartTesterSessionInput, SubmissionResponse, TaskListFilter, TaskListResponse, TaskPreset, TaskStep, TesterDeviceResponse, TesterPoints, TesterProfile, TesterSessionEndReason, TesterSessionResponse, TesterTask, TpkNotification };
788
+ export type { AnonymousLoginResponse, ApiClientConfig, BugCategory, BugReportAttachmentInput, BugReportAttachmentResponse, BugReportPayload, BugReportResponse, BugReportType, BugSeverity, ChecklistRun, ChecklistRunInput, ChecklistStepResult, ChecklistTask, EarningsSummary, EndTesterSessionInput, EnrollmentResponse, FeedbackResponse, KnowledgeBaseAnswer, KnowledgeBaseCitation, KnowledgeFile, KnowledgeFileSummary, LiveNoteInput, MyBugReportSummary, MyBugReportsResponse, NotificationsResult, PayoutRecord, RegisterDeviceInput, RetestItem, RetestStepVerdicts, SdkUpdateInfo, SessionBreadcrumbInput, SessionBreadcrumbsResponse, SessionEventInput, SessionEventsResponse, StartTesterSessionInput, SubmissionResponse, TaskListFilter, TaskListResponse, TaskPreset, TaskStep, TesterDeviceResponse, TesterPoints, TesterProfile, TesterSessionEndReason, TesterSessionResponse, TesterTask, TpkNotification };
package/dist/index.js CHANGED
@@ -249,15 +249,84 @@ var TesterPayKitApiClient = class {
249
249
  /**
250
250
  * Claim a remote AI-tester run waiting for this project.
251
251
  * POST /v1/testers/me/ai-sessions/claim — 204 → null.
252
+ * `appVersion` lets the API hand out AI retests of a fixed bug, which
253
+ * only a build at or above the fixed version may run.
252
254
  */
253
- async claimRemoteAiSession(projectId) {
255
+ async claimRemoteAiSession(projectId, appVersion) {
254
256
  const response = await this.client.post(
255
257
  "/v1/testers/me/ai-sessions/claim",
256
- { project_id: projectId }
258
+ { project_id: projectId, ...appVersion ? { app_version: appVersion } : {} }
257
259
  );
258
260
  if (response.status === 204 || !response.data?.sessionId) return null;
259
261
  return response.data;
260
262
  }
263
+ /**
264
+ * Open a live link to the developer's Claude Code session: returns a
265
+ * one-time WebSocket URL (valid two minutes). Fetch a fresh one for
266
+ * every (re)connect. POST /v1/testers/me/live.
267
+ */
268
+ async openLiveLink(projectId) {
269
+ const response = await this.client.post(
270
+ "/v1/testers/me/live",
271
+ { project_id: projectId }
272
+ );
273
+ const wsUrl = response.data?.wsUrl;
274
+ if (!wsUrl) throw new Error("Live link: response carried no wsUrl");
275
+ return wsUrl;
276
+ }
277
+ /**
278
+ * "Send to Claude": one line plus what the screen showed. Works
279
+ * without an open live link. POST /v1/testers/me/live/notes → note id.
280
+ */
281
+ async sendLiveNote(input) {
282
+ const response = await this.client.post(
283
+ "/v1/testers/me/live/notes",
284
+ {
285
+ project_id: input.projectId,
286
+ text: input.text,
287
+ snapshot: input.snapshot,
288
+ ...input.screenshotBase64 ? { screenshot: input.screenshotBase64 } : {}
289
+ }
290
+ );
291
+ return response.data?.id;
292
+ }
293
+ /**
294
+ * What to test in this app: the project's checklist tasks with this
295
+ * tester's (`mine`) and the AI tester's (`ai`) latest pass.
296
+ * GET /v1/testers/me/checklist?project_id=… — a 404 (tester not in the
297
+ * project yet) yields an empty list.
298
+ */
299
+ async getChecklist(projectId) {
300
+ try {
301
+ const response = await this.client.get(
302
+ "/v1/testers/me/checklist",
303
+ { params: { project_id: projectId } }
304
+ );
305
+ return Array.isArray(response.data?.tasks) ? response.data.tasks : [];
306
+ } catch (e) {
307
+ if (e?.response?.status === 404) return [];
308
+ throw e;
309
+ }
310
+ }
311
+ /**
312
+ * One pass through a checklist task, a verdict per step.
313
+ * POST /v1/testers/me/checklist/{taskId}/runs → the run's status.
314
+ */
315
+ async submitChecklistRun(input) {
316
+ const response = await this.client.post(
317
+ `/v1/testers/me/checklist/${encodeURIComponent(input.taskId)}/runs`,
318
+ {
319
+ project_id: input.projectId,
320
+ step_results: input.stepResults.map((r) => ({
321
+ step: r.step,
322
+ passed: r.passed,
323
+ ...r.note && r.note.trim() ? { note: r.note.trim() } : {}
324
+ })),
325
+ ...input.summary && input.summary.trim() ? { summary: input.summary.trim() } : {}
326
+ }
327
+ );
328
+ return response.data?.status;
329
+ }
261
330
  /**
262
331
  * Attach a file (screenshot, log, voice note) to an already-
263
332
  * submitted bug report. Hits POST /v1/testers/me/bug-reports/
package/dist/index.mjs CHANGED
@@ -215,15 +215,84 @@ var TesterPayKitApiClient = class {
215
215
  /**
216
216
  * Claim a remote AI-tester run waiting for this project.
217
217
  * POST /v1/testers/me/ai-sessions/claim — 204 → null.
218
+ * `appVersion` lets the API hand out AI retests of a fixed bug, which
219
+ * only a build at or above the fixed version may run.
218
220
  */
219
- async claimRemoteAiSession(projectId) {
221
+ async claimRemoteAiSession(projectId, appVersion) {
220
222
  const response = await this.client.post(
221
223
  "/v1/testers/me/ai-sessions/claim",
222
- { project_id: projectId }
224
+ { project_id: projectId, ...appVersion ? { app_version: appVersion } : {} }
223
225
  );
224
226
  if (response.status === 204 || !response.data?.sessionId) return null;
225
227
  return response.data;
226
228
  }
229
+ /**
230
+ * Open a live link to the developer's Claude Code session: returns a
231
+ * one-time WebSocket URL (valid two minutes). Fetch a fresh one for
232
+ * every (re)connect. POST /v1/testers/me/live.
233
+ */
234
+ async openLiveLink(projectId) {
235
+ const response = await this.client.post(
236
+ "/v1/testers/me/live",
237
+ { project_id: projectId }
238
+ );
239
+ const wsUrl = response.data?.wsUrl;
240
+ if (!wsUrl) throw new Error("Live link: response carried no wsUrl");
241
+ return wsUrl;
242
+ }
243
+ /**
244
+ * "Send to Claude": one line plus what the screen showed. Works
245
+ * without an open live link. POST /v1/testers/me/live/notes → note id.
246
+ */
247
+ async sendLiveNote(input) {
248
+ const response = await this.client.post(
249
+ "/v1/testers/me/live/notes",
250
+ {
251
+ project_id: input.projectId,
252
+ text: input.text,
253
+ snapshot: input.snapshot,
254
+ ...input.screenshotBase64 ? { screenshot: input.screenshotBase64 } : {}
255
+ }
256
+ );
257
+ return response.data?.id;
258
+ }
259
+ /**
260
+ * What to test in this app: the project's checklist tasks with this
261
+ * tester's (`mine`) and the AI tester's (`ai`) latest pass.
262
+ * GET /v1/testers/me/checklist?project_id=… — a 404 (tester not in the
263
+ * project yet) yields an empty list.
264
+ */
265
+ async getChecklist(projectId) {
266
+ try {
267
+ const response = await this.client.get(
268
+ "/v1/testers/me/checklist",
269
+ { params: { project_id: projectId } }
270
+ );
271
+ return Array.isArray(response.data?.tasks) ? response.data.tasks : [];
272
+ } catch (e) {
273
+ if (e?.response?.status === 404) return [];
274
+ throw e;
275
+ }
276
+ }
277
+ /**
278
+ * One pass through a checklist task, a verdict per step.
279
+ * POST /v1/testers/me/checklist/{taskId}/runs → the run's status.
280
+ */
281
+ async submitChecklistRun(input) {
282
+ const response = await this.client.post(
283
+ `/v1/testers/me/checklist/${encodeURIComponent(input.taskId)}/runs`,
284
+ {
285
+ project_id: input.projectId,
286
+ step_results: input.stepResults.map((r) => ({
287
+ step: r.step,
288
+ passed: r.passed,
289
+ ...r.note && r.note.trim() ? { note: r.note.trim() } : {}
290
+ })),
291
+ ...input.summary && input.summary.trim() ? { summary: input.summary.trim() } : {}
292
+ }
293
+ );
294
+ return response.data?.status;
295
+ }
227
296
  /**
228
297
  * Attach a file (screenshot, log, voice note) to an already-
229
298
  * submitted bug report. Hits POST /v1/testers/me/bug-reports/
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@testerpaykit/api-client",
3
- "version": "1.5.0",
3
+ "version": "1.7.0",
4
4
  "description": "API client for TesterPayKit backend",
5
5
  "main": "./dist/index.js",
6
6
  "module": "./dist/index.mjs",
@@ -10,6 +10,52 @@ import {
10
10
  RemoteAiSession,
11
11
  } from '@testerpaykit/core';
12
12
 
13
+ /** Body of a "Send to Claude" note (see `sendLiveNote`). */
14
+ export interface LiveNoteInput {
15
+ projectId: string;
16
+ text: string;
17
+ /** Screen snapshot without the screenshot (that goes separately). */
18
+ snapshot: Record<string, unknown>;
19
+ /** Base64 PNG/JPEG, no data-URI prefix. */
20
+ screenshotBase64?: string | null;
21
+ }
22
+
23
+ /** One step verdict of a checklist pass (`step` is 1-based). */
24
+ export interface ChecklistStepResult {
25
+ step: number;
26
+ passed: boolean;
27
+ note?: string;
28
+ }
29
+
30
+ /** The latest pass through a checklist task (by this tester or the AI). */
31
+ export interface ChecklistRun {
32
+ status: 'passed' | 'failed' | 'incomplete' | string;
33
+ steps: ChecklistStepResult[];
34
+ summary?: string;
35
+ at: string;
36
+ tester?: string;
37
+ }
38
+
39
+ /** One task of a project's checklist: what should be tested. */
40
+ export interface ChecklistTask {
41
+ id: string;
42
+ title: string;
43
+ description?: string;
44
+ steps: string[];
45
+ /** This tester's latest pass. */
46
+ mine?: ChecklistRun;
47
+ /** The AI tester's latest pass. */
48
+ ai?: ChecklistRun;
49
+ }
50
+
51
+ /** Body of `submitChecklistRun`. */
52
+ export interface ChecklistRunInput {
53
+ projectId: string;
54
+ taskId: string;
55
+ stepResults: ChecklistStepResult[];
56
+ summary?: string;
57
+ }
58
+
13
59
  export interface ApiClientConfig {
14
60
  baseURL?: string;
15
61
  apiKey: string;
@@ -310,16 +356,92 @@ export class TesterPayKitApiClient implements IApiClient {
310
356
  /**
311
357
  * Claim a remote AI-tester run waiting for this project.
312
358
  * POST /v1/testers/me/ai-sessions/claim — 204 → null.
359
+ * `appVersion` lets the API hand out AI retests of a fixed bug, which
360
+ * only a build at or above the fixed version may run.
313
361
  */
314
- async claimRemoteAiSession(projectId: string): Promise<RemoteAiSession | null> {
362
+ async claimRemoteAiSession(
363
+ projectId: string,
364
+ appVersion?: string,
365
+ ): Promise<RemoteAiSession | null> {
315
366
  const response = await this.client.post<RemoteAiSession>(
316
367
  '/v1/testers/me/ai-sessions/claim',
317
- { project_id: projectId },
368
+ { project_id: projectId, ...(appVersion ? { app_version: appVersion } : {}) },
318
369
  );
319
370
  if (response.status === 204 || !response.data?.sessionId) return null;
320
371
  return response.data;
321
372
  }
322
373
 
374
+ /**
375
+ * Open a live link to the developer's Claude Code session: returns a
376
+ * one-time WebSocket URL (valid two minutes). Fetch a fresh one for
377
+ * every (re)connect. POST /v1/testers/me/live.
378
+ */
379
+ async openLiveLink(projectId: string): Promise<string> {
380
+ const response = await this.client.post<{ wsUrl: string }>(
381
+ '/v1/testers/me/live',
382
+ { project_id: projectId },
383
+ );
384
+ const wsUrl = response.data?.wsUrl;
385
+ if (!wsUrl) throw new Error('Live link: response carried no wsUrl');
386
+ return wsUrl;
387
+ }
388
+
389
+ /**
390
+ * "Send to Claude": one line plus what the screen showed. Works
391
+ * without an open live link. POST /v1/testers/me/live/notes → note id.
392
+ */
393
+ async sendLiveNote(input: LiveNoteInput): Promise<string> {
394
+ const response = await this.client.post<{ id: string }>(
395
+ '/v1/testers/me/live/notes',
396
+ {
397
+ project_id: input.projectId,
398
+ text: input.text,
399
+ snapshot: input.snapshot,
400
+ ...(input.screenshotBase64 ? { screenshot: input.screenshotBase64 } : {}),
401
+ },
402
+ );
403
+ return response.data?.id;
404
+ }
405
+
406
+ /**
407
+ * What to test in this app: the project's checklist tasks with this
408
+ * tester's (`mine`) and the AI tester's (`ai`) latest pass.
409
+ * GET /v1/testers/me/checklist?project_id=… — a 404 (tester not in the
410
+ * project yet) yields an empty list.
411
+ */
412
+ async getChecklist(projectId: string): Promise<ChecklistTask[]> {
413
+ try {
414
+ const response = await this.client.get<{ tasks?: ChecklistTask[] }>(
415
+ '/v1/testers/me/checklist',
416
+ { params: { project_id: projectId } },
417
+ );
418
+ return Array.isArray(response.data?.tasks) ? response.data.tasks : [];
419
+ } catch (e) {
420
+ if ((e as { response?: { status?: number } })?.response?.status === 404) return [];
421
+ throw e;
422
+ }
423
+ }
424
+
425
+ /**
426
+ * One pass through a checklist task, a verdict per step.
427
+ * POST /v1/testers/me/checklist/{taskId}/runs → the run's status.
428
+ */
429
+ async submitChecklistRun(input: ChecklistRunInput): Promise<string> {
430
+ const response = await this.client.post<{ status: string }>(
431
+ `/v1/testers/me/checklist/${encodeURIComponent(input.taskId)}/runs`,
432
+ {
433
+ project_id: input.projectId,
434
+ step_results: input.stepResults.map((r) => ({
435
+ step: r.step,
436
+ passed: r.passed,
437
+ ...(r.note && r.note.trim() ? { note: r.note.trim() } : {}),
438
+ })),
439
+ ...(input.summary && input.summary.trim() ? { summary: input.summary.trim() } : {}),
440
+ },
441
+ );
442
+ return response.data?.status;
443
+ }
444
+
323
445
  /**
324
446
  * Attach a file (screenshot, log, voice note) to an already-
325
447
  * submitted bug report. Hits POST /v1/testers/me/bug-reports/
@@ -182,6 +182,93 @@ describe('TesterPayKitApiClient', () => {
182
182
  });
183
183
  });
184
184
 
185
+ describe('live link', () => {
186
+ it('opens a live link and returns the one-time wsUrl', async () => {
187
+ mockAxiosInstance.post.mockResolvedValue({ data: { wsUrl: 'ws://x/v1/live/ws?t=1' } });
188
+ await expect(client.openLiveLink('p-1')).resolves.toBe('ws://x/v1/live/ws?t=1');
189
+ expect(mockAxiosInstance.post).toHaveBeenCalledWith('/v1/testers/me/live', { project_id: 'p-1' });
190
+ });
191
+
192
+ it('claims a remote AI run with the app version, 204 means none', async () => {
193
+ mockAxiosInstance.post.mockResolvedValue({ status: 200, data: { sessionId: 's-1', wsUrl: 'ws://x' } });
194
+ await expect(client.claimRemoteAiSession('p-1', '1.4.0')).resolves.toMatchObject({ sessionId: 's-1' });
195
+ expect(mockAxiosInstance.post).toHaveBeenCalledWith('/v1/testers/me/ai-sessions/claim', {
196
+ project_id: 'p-1', app_version: '1.4.0',
197
+ });
198
+ mockAxiosInstance.post.mockResolvedValue({ status: 204, data: '' });
199
+ await expect(client.claimRemoteAiSession('p-1')).resolves.toBeNull();
200
+ expect(mockAxiosInstance.post).toHaveBeenLastCalledWith('/v1/testers/me/ai-sessions/claim', {
201
+ project_id: 'p-1',
202
+ });
203
+ });
204
+
205
+ it('rejects when the server sends no wsUrl', async () => {
206
+ mockAxiosInstance.post.mockResolvedValue({ data: {} });
207
+ await expect(client.openLiveLink('p-1')).rejects.toThrow(/wsUrl/);
208
+ });
209
+
210
+ it('sends a note with snapshot and optional screenshot', async () => {
211
+ mockAxiosInstance.post.mockResolvedValue({ data: { id: 'n-1' } });
212
+ await expect(
213
+ client.sendLiveNote({ projectId: 'p-1', text: 'hi', snapshot: { screen: 'Home' }, screenshotBase64: 'AAA' }),
214
+ ).resolves.toBe('n-1');
215
+ expect(mockAxiosInstance.post).toHaveBeenCalledWith('/v1/testers/me/live/notes', {
216
+ project_id: 'p-1', text: 'hi', snapshot: { screen: 'Home' }, screenshot: 'AAA',
217
+ });
218
+ await client.sendLiveNote({ projectId: 'p-1', text: 'x', snapshot: {} });
219
+ expect(mockAxiosInstance.post).toHaveBeenLastCalledWith('/v1/testers/me/live/notes', {
220
+ project_id: 'p-1', text: 'x', snapshot: {},
221
+ });
222
+ });
223
+ });
224
+
225
+ describe('checklist', () => {
226
+ it('reads the checklist of a project', async () => {
227
+ const tasks = [{ id: 't1', title: 'Login', steps: ['Open', 'Sign in'], mine: { status: 'passed', steps: [], at: 'x' } }];
228
+ mockAxiosInstance.get.mockResolvedValue({ data: { tasks } });
229
+ await expect(client.getChecklist('p-1')).resolves.toEqual(tasks);
230
+ expect(mockAxiosInstance.get).toHaveBeenCalledWith('/v1/testers/me/checklist', { params: { project_id: 'p-1' } });
231
+ });
232
+
233
+ it('treats 404 (not in the project yet) as an empty checklist', async () => {
234
+ mockAxiosInstance.get.mockRejectedValue({ response: { status: 404 } });
235
+ await expect(client.getChecklist('p-1')).resolves.toEqual([]);
236
+ });
237
+
238
+ it('rethrows other errors', async () => {
239
+ mockAxiosInstance.get.mockRejectedValue({ response: { status: 500 } });
240
+ await expect(client.getChecklist('p-1')).rejects.toEqual({ response: { status: 500 } });
241
+ });
242
+
243
+ it('returns an empty list when the body carries no tasks', async () => {
244
+ mockAxiosInstance.get.mockResolvedValue({ data: {} });
245
+ await expect(client.getChecklist('p-1')).resolves.toEqual([]);
246
+ });
247
+
248
+ it('submits a run with step verdicts, trimmed notes and summary', async () => {
249
+ mockAxiosInstance.post.mockResolvedValue({ data: { status: 'failed' } });
250
+ await expect(
251
+ client.submitChecklistRun({
252
+ projectId: 'p-1',
253
+ taskId: 't1',
254
+ stepResults: [
255
+ { step: 1, passed: true, note: ' ' },
256
+ { step: 2, passed: false, note: ' button dead ' },
257
+ ],
258
+ summary: ' meh ',
259
+ }),
260
+ ).resolves.toBe('failed');
261
+ expect(mockAxiosInstance.post).toHaveBeenCalledWith('/v1/testers/me/checklist/t1/runs', {
262
+ project_id: 'p-1',
263
+ step_results: [
264
+ { step: 1, passed: true },
265
+ { step: 2, passed: false, note: 'button dead' },
266
+ ],
267
+ summary: 'meh',
268
+ });
269
+ });
270
+ });
271
+
185
272
  describe('tester sessions', () => {
186
273
  it('should start a tester session with server contract field names', async () => {
187
274
  const response = {