@testerpaykit/sdk 1.1.0 → 1.2.0

package/dist/index.d.mts

@@ -170,6 +170,35 @@ interface TesterPayKitConfig {
      * Contract: configuration.weeklySubmissionDay
      */
     weeklySubmissionDay?: number;
+    /**
+     * Extra state the live link to Claude Code reports as `app_state`
+     * (MCP `device_snapshot`). Must return JSON-serialisable data. Can also be
+     * set later via `sdk.liveStateProvider`.
+     */
+    liveStateProvider?: () => unknown;
+}
+/** One step verdict of a checklist pass (`step` is 1-based). */
+interface ChecklistStepResult {
+    step: number;
+    passed: boolean;
+    note?: string;
+}
+/** The latest pass through a checklist task (by this tester or the AI). */
+interface ChecklistRun {
+    status: 'passed' | 'failed' | 'incomplete' | string;
+    steps: ChecklistStepResult[];
+    summary?: string;
+    at: string;
+    tester?: string;
+}
+/** One task of a project's checklist: what should be tested. */
+interface ChecklistTask {
+    id: string;
+    title: string;
+    description?: string;
+    steps: string[];
+    mine?: ChecklistRun;
+    ai?: ChecklistRun;
 }
 /**
  * Main TesterPayKit SDK class.
@@ -216,6 +245,11 @@ declare class TesterPayKit {
     readonly environment: 'local' | 'prod';
     private static readonly LOG_BUFFER_MAX;
     private _logBuffer;
+    /**
+     * Host hook for the live link's `app_state` (see
+     * `TesterPayKitConfig.liveStateProvider`). Settable at any time.
+     */
+    liveStateProvider: (() => unknown) | null;
     constructor(config: TesterPayKitConfig);
     get onTokenReady(): Promise<void>;
     get isAuthenticated(): boolean;
@@ -614,6 +648,37 @@ declare class TesterPayKit {
      * Used by TpkWorkboardScreen to show the current build info block.
      */
     getAppInfo(): AppMetadata;
+    private _liveApi;
+    /**
+     * One-time WebSocket URL for the live link to the developer's Claude Code
+     * session (POST /v1/testers/me/live). Fetch a fresh one for every connect.
+     * Throws when the call fails.
+     */
+    openLiveLink(): Promise<string>;
+    /**
+     * "Send to Claude": one line plus what the screen showed
+     * (POST /v1/testers/me/live/notes). Throws when the call fails.
+     */
+    sendLiveNote(input: {
+        text: string;
+        snapshot: Record<string, unknown>;
+        screenshotBase64?: string | null;
+    }): Promise<string>;
+    /**
+     * The project's checklist ("What to test") with this tester's last pass.
+     * Soft-fails to [] (offline, not logged in, older api-client).
+     */
+    getChecklist(): Promise<ChecklistTask[]>;
+    /**
+     * One pass through a checklist task, a verdict per step
+     * (POST /v1/testers/me/checklist/:id/runs). Resolves with the run status;
+     * throws when the call fails.
+     */
+    submitChecklistRun(input: {
+        taskId: string;
+        stepResults: ChecklistStepResult[];
+        summary?: string;
+    }): Promise<string>;
     /**
      * Fetch the tester's assigned tasks.
      * Delegates to apiClient.getMyTasks. Soft-fails to an empty TaskListResponse
@@ -905,4 +970,4 @@ declare class DeviceIdManager {
 }
 
 export { DeviceIdManager, EventTracker, MetricsAggregator, Outbox, SessionManager, TesterPayKit, ValidationConstants };
-export type { CaptureFlags, MetricsAggregatorConfig, SessionEndReason, TesterPayKitConfig };
+export type { CaptureFlags, ChecklistRun, ChecklistStepResult, ChecklistTask, MetricsAggregatorConfig, SessionEndReason, TesterPayKitConfig };

package/dist/index.d.ts

@@ -170,6 +170,35 @@ interface TesterPayKitConfig {
      * Contract: configuration.weeklySubmissionDay
      */
     weeklySubmissionDay?: number;
+    /**
+     * Extra state the live link to Claude Code reports as `app_state`
+     * (MCP `device_snapshot`). Must return JSON-serialisable data. Can also be
+     * set later via `sdk.liveStateProvider`.
+     */
+    liveStateProvider?: () => unknown;
+}
+/** One step verdict of a checklist pass (`step` is 1-based). */
+interface ChecklistStepResult {
+    step: number;
+    passed: boolean;
+    note?: string;
+}
+/** The latest pass through a checklist task (by this tester or the AI). */
+interface ChecklistRun {
+    status: 'passed' | 'failed' | 'incomplete' | string;
+    steps: ChecklistStepResult[];
+    summary?: string;
+    at: string;
+    tester?: string;
+}
+/** One task of a project's checklist: what should be tested. */
+interface ChecklistTask {
+    id: string;
+    title: string;
+    description?: string;
+    steps: string[];
+    mine?: ChecklistRun;
+    ai?: ChecklistRun;
 }
 /**
  * Main TesterPayKit SDK class.
@@ -216,6 +245,11 @@ declare class TesterPayKit {
     readonly environment: 'local' | 'prod';
     private static readonly LOG_BUFFER_MAX;
     private _logBuffer;
+    /**
+     * Host hook for the live link's `app_state` (see
+     * `TesterPayKitConfig.liveStateProvider`). Settable at any time.
+     */
+    liveStateProvider: (() => unknown) | null;
     constructor(config: TesterPayKitConfig);
     get onTokenReady(): Promise<void>;
     get isAuthenticated(): boolean;
@@ -614,6 +648,37 @@ declare class TesterPayKit {
      * Used by TpkWorkboardScreen to show the current build info block.
      */
     getAppInfo(): AppMetadata;
+    private _liveApi;
+    /**
+     * One-time WebSocket URL for the live link to the developer's Claude Code
+     * session (POST /v1/testers/me/live). Fetch a fresh one for every connect.
+     * Throws when the call fails.
+     */
+    openLiveLink(): Promise<string>;
+    /**
+     * "Send to Claude": one line plus what the screen showed
+     * (POST /v1/testers/me/live/notes). Throws when the call fails.
+     */
+    sendLiveNote(input: {
+        text: string;
+        snapshot: Record<string, unknown>;
+        screenshotBase64?: string | null;
+    }): Promise<string>;
+    /**
+     * The project's checklist ("What to test") with this tester's last pass.
+     * Soft-fails to [] (offline, not logged in, older api-client).
+     */
+    getChecklist(): Promise<ChecklistTask[]>;
+    /**
+     * One pass through a checklist task, a verdict per step
+     * (POST /v1/testers/me/checklist/:id/runs). Resolves with the run status;
+     * throws when the call fails.
+     */
+    submitChecklistRun(input: {
+        taskId: string;
+        stepResults: ChecklistStepResult[];
+        summary?: string;
+    }): Promise<string>;
     /**
      * Fetch the tester's assigned tasks.
      * Delegates to apiClient.getMyTasks. Soft-fails to an empty TaskListResponse
@@ -905,4 +970,4 @@ declare class DeviceIdManager {
 }
 
 export { DeviceIdManager, EventTracker, MetricsAggregator, Outbox, SessionManager, TesterPayKit, ValidationConstants };
-export type { CaptureFlags, MetricsAggregatorConfig, SessionEndReason, TesterPayKitConfig };
+export type { CaptureFlags, ChecklistRun, ChecklistStepResult, ChecklistTask, MetricsAggregatorConfig, SessionEndReason, TesterPayKitConfig };

package/dist/index.js

@@ -930,6 +930,11 @@ var _TesterPayKit = class _TesterPayKit {
     this._serverSessionId = null;
     this._pendingSessionEvents = [];
     this._logBuffer = [];
+    /**
+     * Host hook for the live link's `app_state` (see
+     * `TesterPayKitConfig.liveStateProvider`). Settable at any time.
+     */
+    this.liveStateProvider = null;
     this._serverSessionInFlight = null;
     this.config = {
       autoStartSession: true,
@@ -962,6 +967,7 @@ var _TesterPayKit = class _TesterPayKit {
     this.anonymousAuthReady = new Promise((resolve) => {
       this._resolveAnonymousAuth = resolve;
     });
+    this.liveStateProvider = config.liveStateProvider ?? null;
   }
   // ── Alias (contract: lifecycle.readiness.onTokenReady) ─────────────────────
   get onTokenReady() {
@@ -1933,6 +1939,54 @@ var _TesterPayKit = class _TesterPayKit {
   getAppInfo() {
     return this.config.appMetadata;
   }
+  // ── Live link to Claude Code + checklist ──────────────────────────────────
+  _liveApi(name) {
+    const api = this.config.apiClient;
+    if (!api || typeof api[name] !== "function") {
+      throw new Error(`apiClient does not implement ${name} (needs @testerpaykit/api-client >= 1.7.0)`);
+    }
+    return api;
+  }
+  /**
+   * One-time WebSocket URL for the live link to the developer's Claude Code
+   * session (POST /v1/testers/me/live). Fetch a fresh one for every connect.
+   * Throws when the call fails.
+   */
+  async openLiveLink() {
+    const api = this._liveApi("openLiveLink");
+    return api.openLiveLink(this.config.projectId);
+  }
+  /**
+   * "Send to Claude": one line plus what the screen showed
+   * (POST /v1/testers/me/live/notes). Throws when the call fails.
+   */
+  async sendLiveNote(input) {
+    const api = this._liveApi("sendLiveNote");
+    return api.sendLiveNote({ projectId: this.config.projectId, ...input });
+  }
+  /**
+   * The project's checklist ("What to test") with this tester's last pass.
+   * Soft-fails to [] (offline, not logged in, older api-client).
+   */
+  async getChecklist() {
+    try {
+      const api = this._liveApi("getChecklist");
+      const tasks = await api.getChecklist(this.config.projectId);
+      return Array.isArray(tasks) ? tasks.filter((t) => t && typeof t.id === "string" && Array.isArray(t.steps)) : [];
+    } catch (e) {
+      this.log(`getChecklist: failed \u2014 ${String(e)}`);
+      return [];
+    }
+  }
+  /**
+   * One pass through a checklist task, a verdict per step
+   * (POST /v1/testers/me/checklist/:id/runs). Resolves with the run status;
+   * throws when the call fails.
+   */
+  async submitChecklistRun(input) {
+    const api = this._liveApi("submitChecklistRun");
+    return api.submitChecklistRun({ projectId: this.config.projectId, ...input });
+  }
   /**
    * Fetch the tester's assigned tasks.
    * Delegates to apiClient.getMyTasks. Soft-fails to an empty TaskListResponse

package/dist/index.mjs

@@ -897,6 +897,11 @@ var _TesterPayKit = class _TesterPayKit {
     this._serverSessionId = null;
     this._pendingSessionEvents = [];
     this._logBuffer = [];
+    /**
+     * Host hook for the live link's `app_state` (see
+     * `TesterPayKitConfig.liveStateProvider`). Settable at any time.
+     */
+    this.liveStateProvider = null;
     this._serverSessionInFlight = null;
     this.config = {
       autoStartSession: true,
@@ -929,6 +934,7 @@ var _TesterPayKit = class _TesterPayKit {
     this.anonymousAuthReady = new Promise((resolve) => {
       this._resolveAnonymousAuth = resolve;
     });
+    this.liveStateProvider = config.liveStateProvider ?? null;
   }
   // ── Alias (contract: lifecycle.readiness.onTokenReady) ─────────────────────
   get onTokenReady() {
@@ -1900,6 +1906,54 @@ var _TesterPayKit = class _TesterPayKit {
   getAppInfo() {
     return this.config.appMetadata;
   }
+  // ── Live link to Claude Code + checklist ──────────────────────────────────
+  _liveApi(name) {
+    const api = this.config.apiClient;
+    if (!api || typeof api[name] !== "function") {
+      throw new Error(`apiClient does not implement ${name} (needs @testerpaykit/api-client >= 1.7.0)`);
+    }
+    return api;
+  }
+  /**
+   * One-time WebSocket URL for the live link to the developer's Claude Code
+   * session (POST /v1/testers/me/live). Fetch a fresh one for every connect.
+   * Throws when the call fails.
+   */
+  async openLiveLink() {
+    const api = this._liveApi("openLiveLink");
+    return api.openLiveLink(this.config.projectId);
+  }
+  /**
+   * "Send to Claude": one line plus what the screen showed
+   * (POST /v1/testers/me/live/notes). Throws when the call fails.
+   */
+  async sendLiveNote(input) {
+    const api = this._liveApi("sendLiveNote");
+    return api.sendLiveNote({ projectId: this.config.projectId, ...input });
+  }
+  /**
+   * The project's checklist ("What to test") with this tester's last pass.
+   * Soft-fails to [] (offline, not logged in, older api-client).
+   */
+  async getChecklist() {
+    try {
+      const api = this._liveApi("getChecklist");
+      const tasks = await api.getChecklist(this.config.projectId);
+      return Array.isArray(tasks) ? tasks.filter((t) => t && typeof t.id === "string" && Array.isArray(t.steps)) : [];
+    } catch (e) {
+      this.log(`getChecklist: failed \u2014 ${String(e)}`);
+      return [];
+    }
+  }
+  /**
+   * One pass through a checklist task, a verdict per step
+   * (POST /v1/testers/me/checklist/:id/runs). Resolves with the run status;
+   * throws when the call fails.
+   */
+  async submitChecklistRun(input) {
+    const api = this._liveApi("submitChecklistRun");
+    return api.submitChecklistRun({ projectId: this.config.projectId, ...input });
+  }
   /**
    * Fetch the tester's assigned tasks.
    * Delegates to apiClient.getMyTasks. Soft-fails to an empty TaskListResponse

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@testerpaykit/sdk",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "description": "TesterPayKit SDK - Core business logic",
   "files": [
     "dist",