@testerpaykit/api-client 1.7.0 → 2.0.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 CHANGED
@@ -2,6 +2,20 @@
2
2
 
3
3
  All notable changes to `@testerpaykit/api-client` are documented here.
4
4
 
5
+ ## 2.0.0 — 2026-11-07
6
+
7
+ Breaking: `submitSessionEndFeedback` removed.
8
+
9
+ ### Added
10
+ - `onTesterGate` — called on any 403 `phone_required` /
11
+ `approval_required` answer (SDKs hide their tester UI on it). Type
12
+ `TesterGateReason`.
13
+
14
+ ### Removed
15
+ - `submitSessionEndFeedback` and `FeedbackResponse`: `/v1/session-feedback`
16
+ never existed on the API. Session feedback goes out as a
17
+ `generalFeedback` bug report.
18
+
5
19
  ## 1.7.0 — 2026-11-01
6
20
 
7
21
  ### Added
package/dist/index.d.mts CHANGED
@@ -1,5 +1,122 @@
1
1
  import { TokenManager, IApiClient, LoginRequest, LoginResponse, WeeklySummary, RemoteAiSession, VoiceBugExtractResponse, QuickActionKind } from '@testerpaykit/core';
2
2
 
3
+ /** `play` = play money in the pilot: real ledger rows, never a payout.
4
+ * Every UI labels such amounts "Spielgeld · Pilot" / "Play money · pilot". */
5
+ type MoneyMode = 'play' | 'test' | 'live';
6
+ type WorkState = 'offered' | 'active' | 'paused' | 'review' | 'disputed' | 'approved' | 'cancelled';
7
+ interface PaidAssignment {
8
+ id: string;
9
+ project_id: string;
10
+ tester_id: string;
11
+ title: string;
12
+ project_name: string;
13
+ mode: MoneyMode;
14
+ terms_version: 1;
15
+ rate_cents: number;
16
+ minimum_cents: number;
17
+ budget_cents: number;
18
+ seconds: number;
19
+ running_since: string | null;
20
+ state: WorkState;
21
+ revision: number;
22
+ amount_cents: number | null;
23
+ review_due: string | null;
24
+ review_note: string | null;
25
+ completion_note: string | null;
26
+ }
27
+ /** time = paid assignment · task = checklist task on its announced time ·
28
+ * bonus = idea bonus · bug_bonus · reproduction · retest (one per round). */
29
+ type MoneyKind = 'time' | 'task' | 'bonus' | 'bug_bonus' | 'reproduction' | 'retest' | 'start_bonus';
30
+ interface MoneyEntry {
31
+ id: string;
32
+ project_id: string;
33
+ project_name: string;
34
+ tester_id: string;
35
+ mode: MoneyMode;
36
+ kind: MoneyKind;
37
+ reason: string;
38
+ amount_cents: number;
39
+ currency: 'eur';
40
+ /** review = waits for the 3-working-day window, then released. */
41
+ status: 'review' | 'approved' | 'processing' | 'transferred' | 'held';
42
+ units: number;
43
+ review_due: string | null;
44
+ review_note: string | null;
45
+ bug_id: string | null;
46
+ task_preset_id: string | null;
47
+ created_at: string;
48
+ transfer_id: string | null;
49
+ }
50
+ /** Sums in the current mode, in cents. Bonuses never count towards the 5 € floor. */
51
+ interface MoneyTotals {
52
+ in_review_cents: number;
53
+ released_cents: number;
54
+ bonus_cents: number;
55
+ held_cents: number;
56
+ total_cents: number;
57
+ }
58
+ interface CompensationRates {
59
+ rate_cents_per_minute: number;
60
+ minimum_cents: number;
61
+ bug_bonus_cents: {
62
+ easy: number;
63
+ medium: number;
64
+ hard: number;
65
+ };
66
+ reproduction_cents: number;
67
+ retest_per_fix_cents: number;
68
+ retest_round_minimum_cents: number;
69
+ idea_bonus_choices_cents: number[];
70
+ review_working_days: number;
71
+ /** Start bonus, booked once per person on the first phone confirmation. */
72
+ start_bonus_cents?: number;
73
+ }
74
+ interface CompensationWallet {
75
+ /** Current mode; `play` = label every amount as play money. */
76
+ mode: MoneyMode;
77
+ currency: 'eur';
78
+ server_time: string;
79
+ rates: CompensationRates;
80
+ /** The person = every app install with the same confirmed phone. */
81
+ person: {
82
+ handle: string | null;
83
+ phone_confirmed: boolean;
84
+ tester_count: number;
85
+ apps: Array<{
86
+ project_id: string;
87
+ project_name: string;
88
+ }>;
89
+ };
90
+ /** Whole person across apps … */
91
+ totals: MoneyTotals;
92
+ /** … and the share of this app install. */
93
+ this_app: MoneyTotals;
94
+ assignments: PaidAssignment[];
95
+ entries: MoneyEntry[];
96
+ balances: Record<MoneyMode, Record<MoneyEntry['status'], number>>;
97
+ legacy: Array<{
98
+ id: string;
99
+ source: string;
100
+ amount_cents: number;
101
+ status: string;
102
+ }>;
103
+ }
104
+ interface WorkCommand {
105
+ assignment_id: string;
106
+ request_id: string;
107
+ revision: number;
108
+ action: 'start' | 'pause' | 'submit' | 'submit_partial' | 'decline';
109
+ accept_terms_version?: 1;
110
+ seconds?: number;
111
+ note?: string;
112
+ }
113
+ interface PushRegistration {
114
+ installation_id: string;
115
+ app_id: string;
116
+ token?: string;
117
+ enabled: boolean;
118
+ }
119
+
3
120
  /** Body of a "Send to Claude" note (see `sendLiveNote`). */
4
121
  interface LiveNoteInput {
5
122
  projectId: string;
@@ -54,10 +171,18 @@ interface ApiClientConfig {
54
171
  * - Request/response interceptors for auth headers
55
172
  * - Integration with TokenManager for token lifecycle
56
173
  */
174
+ /** The tester gate's 403 codes (migrations 075 + 077). */
175
+ type TesterGateReason = 'phone_required' | 'approval_required';
57
176
  declare class TesterPayKitApiClient implements IApiClient {
58
177
  private client;
59
178
  private tokenManager;
60
179
  private apiKey;
180
+ /**
181
+ * Called on any 403 `phone_required` / `approval_required` answer: the
182
+ * tester is not (or no longer) cleared to report. SDKs hide their
183
+ * tester UI on it. The request still rejects as before.
184
+ */
185
+ onTesterGate: ((reason: TesterGateReason) => void) | null;
61
186
  constructor(config: ApiClientConfig);
62
187
  /**
63
188
  * Setup request/response interceptors for JWT authentication.
@@ -263,6 +388,34 @@ declare class TesterPayKitApiClient implements IApiClient {
263
388
  * GET /v1/testers/me/profile.
264
389
  */
265
390
  getMyProfile(): Promise<TesterProfile>;
391
+ /**
392
+ * POST /v1/testers/me/phone/start — sends a 6-digit SMS code.
393
+ * Throws with status 400 (invalid_phone), 429 (too_many_codes) or
394
+ * 503 (sms_not_configured: the server cannot send SMS yet).
395
+ */
396
+ startPhoneVerification(phone: string): Promise<PhoneStartResponse>;
397
+ /**
398
+ * POST /v1/testers/me/phone/confirm — confirms the code. Returns the
399
+ * tester's handle; the same number on another install hands it over.
400
+ * `device` binds the number to this physical device (migration 077):
401
+ * a number already confirmed on another device throws 409
402
+ * `device_not_allowed` until an admin allows the new one.
403
+ */
404
+ confirmPhoneVerification(verificationId: string, code: string, device?: {
405
+ deviceKey: string;
406
+ platform: 'ios' | 'android' | 'web';
407
+ }): Promise<PhoneConfirmResponse>;
408
+ getCompensation(): Promise<CompensationWallet>;
409
+ recordPaidWork(command: WorkCommand): Promise<PaidAssignment>;
410
+ registerCompensationPush(registration: PushRegistration): Promise<void>;
411
+ getPayoutAccount(): Promise<{
412
+ has_account: boolean;
413
+ transfers_active: boolean;
414
+ payments_configured: boolean;
415
+ }>;
416
+ createPayoutAccountLink(): Promise<{
417
+ url: string;
418
+ }>;
266
419
  /** GET /v1/testers/me/points — current point balance + breakdown. */
267
420
  getMyPoints(): Promise<TesterPoints>;
268
421
  /**
@@ -338,11 +491,6 @@ declare class TesterPayKitApiClient implements IApiClient {
338
491
  * Server keys on device_token — a second POST with the same token updates the row.
339
492
  */
340
493
  registerDevice(input: RegisterDeviceInput): Promise<TesterDeviceResponse>;
341
- /**
342
- * POST /v1/session-feedback
343
- * Submit end-of-session feedback (rating, comments, etc.).
344
- */
345
- submitSessionEndFeedback(payload: Record<string, unknown>): Promise<FeedbackResponse>;
346
494
  /**
347
495
  * Upload an attachment directly (not tied to a specific bug report).
348
496
  * POST /v1/attachments — alternate path from the contract alongside
@@ -667,13 +815,30 @@ interface EnrollmentResponse {
667
815
  interface TesterProfile {
668
816
  id: string;
669
817
  email?: string | null;
818
+ /** System handle, e.g. "sad-banana" (migration 074). */
670
819
  handle?: string | null;
820
+ /** True once this install confirmed a phone number. */
821
+ phoneVerified?: boolean;
822
+ /** True once an admin approved the person (migration 077). */
823
+ approved?: boolean;
671
824
  fullName?: string | null;
672
825
  rating?: number | null;
673
826
  pointsTotal?: number | null;
674
827
  status?: string;
675
828
  createdAt?: string;
676
829
  }
830
+ interface PhoneStartResponse {
831
+ verificationId: string;
832
+ expiresInSeconds: number;
833
+ /** Only returned by a development server. */
834
+ devCode?: string;
835
+ }
836
+ interface PhoneConfirmResponse {
837
+ handle: string;
838
+ phoneVerified: boolean;
839
+ /** Tester status after the confirmation (e.g. `active`, `pending`). */
840
+ status?: string | null;
841
+ }
677
842
  interface TesterPoints {
678
843
  total: number;
679
844
  breakdown?: Record<string, number>;
@@ -730,12 +895,6 @@ interface TesterDeviceResponse {
730
895
  deviceToken: string;
731
896
  deviceType: string;
732
897
  }
733
- /** Response from POST /v1/session-feedback */
734
- interface FeedbackResponse {
735
- id: string;
736
- status: string;
737
- message?: string;
738
- }
739
898
  /** A single retest item from GET /v1/testers/me/retests */
740
899
  interface RetestItem {
741
900
  id: string;
@@ -785,4 +944,4 @@ interface TaskStep {
785
944
  }
786
945
 
787
946
  export { TesterPayKitApiClient };
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 };
947
+ export type { AnonymousLoginResponse, ApiClientConfig, BugCategory, BugReportAttachmentInput, BugReportAttachmentResponse, BugReportPayload, BugReportResponse, BugReportType, BugSeverity, ChecklistRun, ChecklistRunInput, ChecklistStepResult, ChecklistTask, CompensationRates, CompensationWallet, EarningsSummary, EndTesterSessionInput, EnrollmentResponse, KnowledgeBaseAnswer, KnowledgeBaseCitation, KnowledgeFile, KnowledgeFileSummary, LiveNoteInput, MoneyEntry, MoneyKind, MoneyMode, MoneyTotals, MyBugReportSummary, MyBugReportsResponse, NotificationsResult, PaidAssignment, PayoutRecord, PhoneConfirmResponse, PhoneStartResponse, PushRegistration, RegisterDeviceInput, RetestItem, RetestStepVerdicts, SdkUpdateInfo, SessionBreadcrumbInput, SessionBreadcrumbsResponse, SessionEventInput, SessionEventsResponse, StartTesterSessionInput, SubmissionResponse, TaskListFilter, TaskListResponse, TaskPreset, TaskStep, TesterDeviceResponse, TesterGateReason, TesterPoints, TesterProfile, TesterSessionEndReason, TesterSessionResponse, TesterTask, TpkNotification, WorkCommand, WorkState };
package/dist/index.d.ts CHANGED
@@ -1,5 +1,122 @@
1
1
  import { TokenManager, IApiClient, LoginRequest, LoginResponse, WeeklySummary, RemoteAiSession, VoiceBugExtractResponse, QuickActionKind } from '@testerpaykit/core';
2
2
 
3
+ /** `play` = play money in the pilot: real ledger rows, never a payout.
4
+ * Every UI labels such amounts "Spielgeld · Pilot" / "Play money · pilot". */
5
+ type MoneyMode = 'play' | 'test' | 'live';
6
+ type WorkState = 'offered' | 'active' | 'paused' | 'review' | 'disputed' | 'approved' | 'cancelled';
7
+ interface PaidAssignment {
8
+ id: string;
9
+ project_id: string;
10
+ tester_id: string;
11
+ title: string;
12
+ project_name: string;
13
+ mode: MoneyMode;
14
+ terms_version: 1;
15
+ rate_cents: number;
16
+ minimum_cents: number;
17
+ budget_cents: number;
18
+ seconds: number;
19
+ running_since: string | null;
20
+ state: WorkState;
21
+ revision: number;
22
+ amount_cents: number | null;
23
+ review_due: string | null;
24
+ review_note: string | null;
25
+ completion_note: string | null;
26
+ }
27
+ /** time = paid assignment · task = checklist task on its announced time ·
28
+ * bonus = idea bonus · bug_bonus · reproduction · retest (one per round). */
29
+ type MoneyKind = 'time' | 'task' | 'bonus' | 'bug_bonus' | 'reproduction' | 'retest' | 'start_bonus';
30
+ interface MoneyEntry {
31
+ id: string;
32
+ project_id: string;
33
+ project_name: string;
34
+ tester_id: string;
35
+ mode: MoneyMode;
36
+ kind: MoneyKind;
37
+ reason: string;
38
+ amount_cents: number;
39
+ currency: 'eur';
40
+ /** review = waits for the 3-working-day window, then released. */
41
+ status: 'review' | 'approved' | 'processing' | 'transferred' | 'held';
42
+ units: number;
43
+ review_due: string | null;
44
+ review_note: string | null;
45
+ bug_id: string | null;
46
+ task_preset_id: string | null;
47
+ created_at: string;
48
+ transfer_id: string | null;
49
+ }
50
+ /** Sums in the current mode, in cents. Bonuses never count towards the 5 € floor. */
51
+ interface MoneyTotals {
52
+ in_review_cents: number;
53
+ released_cents: number;
54
+ bonus_cents: number;
55
+ held_cents: number;
56
+ total_cents: number;
57
+ }
58
+ interface CompensationRates {
59
+ rate_cents_per_minute: number;
60
+ minimum_cents: number;
61
+ bug_bonus_cents: {
62
+ easy: number;
63
+ medium: number;
64
+ hard: number;
65
+ };
66
+ reproduction_cents: number;
67
+ retest_per_fix_cents: number;
68
+ retest_round_minimum_cents: number;
69
+ idea_bonus_choices_cents: number[];
70
+ review_working_days: number;
71
+ /** Start bonus, booked once per person on the first phone confirmation. */
72
+ start_bonus_cents?: number;
73
+ }
74
+ interface CompensationWallet {
75
+ /** Current mode; `play` = label every amount as play money. */
76
+ mode: MoneyMode;
77
+ currency: 'eur';
78
+ server_time: string;
79
+ rates: CompensationRates;
80
+ /** The person = every app install with the same confirmed phone. */
81
+ person: {
82
+ handle: string | null;
83
+ phone_confirmed: boolean;
84
+ tester_count: number;
85
+ apps: Array<{
86
+ project_id: string;
87
+ project_name: string;
88
+ }>;
89
+ };
90
+ /** Whole person across apps … */
91
+ totals: MoneyTotals;
92
+ /** … and the share of this app install. */
93
+ this_app: MoneyTotals;
94
+ assignments: PaidAssignment[];
95
+ entries: MoneyEntry[];
96
+ balances: Record<MoneyMode, Record<MoneyEntry['status'], number>>;
97
+ legacy: Array<{
98
+ id: string;
99
+ source: string;
100
+ amount_cents: number;
101
+ status: string;
102
+ }>;
103
+ }
104
+ interface WorkCommand {
105
+ assignment_id: string;
106
+ request_id: string;
107
+ revision: number;
108
+ action: 'start' | 'pause' | 'submit' | 'submit_partial' | 'decline';
109
+ accept_terms_version?: 1;
110
+ seconds?: number;
111
+ note?: string;
112
+ }
113
+ interface PushRegistration {
114
+ installation_id: string;
115
+ app_id: string;
116
+ token?: string;
117
+ enabled: boolean;
118
+ }
119
+
3
120
  /** Body of a "Send to Claude" note (see `sendLiveNote`). */
4
121
  interface LiveNoteInput {
5
122
  projectId: string;
@@ -54,10 +171,18 @@ interface ApiClientConfig {
54
171
  * - Request/response interceptors for auth headers
55
172
  * - Integration with TokenManager for token lifecycle
56
173
  */
174
+ /** The tester gate's 403 codes (migrations 075 + 077). */
175
+ type TesterGateReason = 'phone_required' | 'approval_required';
57
176
  declare class TesterPayKitApiClient implements IApiClient {
58
177
  private client;
59
178
  private tokenManager;
60
179
  private apiKey;
180
+ /**
181
+ * Called on any 403 `phone_required` / `approval_required` answer: the
182
+ * tester is not (or no longer) cleared to report. SDKs hide their
183
+ * tester UI on it. The request still rejects as before.
184
+ */
185
+ onTesterGate: ((reason: TesterGateReason) => void) | null;
61
186
  constructor(config: ApiClientConfig);
62
187
  /**
63
188
  * Setup request/response interceptors for JWT authentication.
@@ -263,6 +388,34 @@ declare class TesterPayKitApiClient implements IApiClient {
263
388
  * GET /v1/testers/me/profile.
264
389
  */
265
390
  getMyProfile(): Promise<TesterProfile>;
391
+ /**
392
+ * POST /v1/testers/me/phone/start — sends a 6-digit SMS code.
393
+ * Throws with status 400 (invalid_phone), 429 (too_many_codes) or
394
+ * 503 (sms_not_configured: the server cannot send SMS yet).
395
+ */
396
+ startPhoneVerification(phone: string): Promise<PhoneStartResponse>;
397
+ /**
398
+ * POST /v1/testers/me/phone/confirm — confirms the code. Returns the
399
+ * tester's handle; the same number on another install hands it over.
400
+ * `device` binds the number to this physical device (migration 077):
401
+ * a number already confirmed on another device throws 409
402
+ * `device_not_allowed` until an admin allows the new one.
403
+ */
404
+ confirmPhoneVerification(verificationId: string, code: string, device?: {
405
+ deviceKey: string;
406
+ platform: 'ios' | 'android' | 'web';
407
+ }): Promise<PhoneConfirmResponse>;
408
+ getCompensation(): Promise<CompensationWallet>;
409
+ recordPaidWork(command: WorkCommand): Promise<PaidAssignment>;
410
+ registerCompensationPush(registration: PushRegistration): Promise<void>;
411
+ getPayoutAccount(): Promise<{
412
+ has_account: boolean;
413
+ transfers_active: boolean;
414
+ payments_configured: boolean;
415
+ }>;
416
+ createPayoutAccountLink(): Promise<{
417
+ url: string;
418
+ }>;
266
419
  /** GET /v1/testers/me/points — current point balance + breakdown. */
267
420
  getMyPoints(): Promise<TesterPoints>;
268
421
  /**
@@ -338,11 +491,6 @@ declare class TesterPayKitApiClient implements IApiClient {
338
491
  * Server keys on device_token — a second POST with the same token updates the row.
339
492
  */
340
493
  registerDevice(input: RegisterDeviceInput): Promise<TesterDeviceResponse>;
341
- /**
342
- * POST /v1/session-feedback
343
- * Submit end-of-session feedback (rating, comments, etc.).
344
- */
345
- submitSessionEndFeedback(payload: Record<string, unknown>): Promise<FeedbackResponse>;
346
494
  /**
347
495
  * Upload an attachment directly (not tied to a specific bug report).
348
496
  * POST /v1/attachments — alternate path from the contract alongside
@@ -667,13 +815,30 @@ interface EnrollmentResponse {
667
815
  interface TesterProfile {
668
816
  id: string;
669
817
  email?: string | null;
818
+ /** System handle, e.g. "sad-banana" (migration 074). */
670
819
  handle?: string | null;
820
+ /** True once this install confirmed a phone number. */
821
+ phoneVerified?: boolean;
822
+ /** True once an admin approved the person (migration 077). */
823
+ approved?: boolean;
671
824
  fullName?: string | null;
672
825
  rating?: number | null;
673
826
  pointsTotal?: number | null;
674
827
  status?: string;
675
828
  createdAt?: string;
676
829
  }
830
+ interface PhoneStartResponse {
831
+ verificationId: string;
832
+ expiresInSeconds: number;
833
+ /** Only returned by a development server. */
834
+ devCode?: string;
835
+ }
836
+ interface PhoneConfirmResponse {
837
+ handle: string;
838
+ phoneVerified: boolean;
839
+ /** Tester status after the confirmation (e.g. `active`, `pending`). */
840
+ status?: string | null;
841
+ }
677
842
  interface TesterPoints {
678
843
  total: number;
679
844
  breakdown?: Record<string, number>;
@@ -730,12 +895,6 @@ interface TesterDeviceResponse {
730
895
  deviceToken: string;
731
896
  deviceType: string;
732
897
  }
733
- /** Response from POST /v1/session-feedback */
734
- interface FeedbackResponse {
735
- id: string;
736
- status: string;
737
- message?: string;
738
- }
739
898
  /** A single retest item from GET /v1/testers/me/retests */
740
899
  interface RetestItem {
741
900
  id: string;
@@ -785,4 +944,4 @@ interface TaskStep {
785
944
  }
786
945
 
787
946
  export { TesterPayKitApiClient };
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 };
947
+ export type { AnonymousLoginResponse, ApiClientConfig, BugCategory, BugReportAttachmentInput, BugReportAttachmentResponse, BugReportPayload, BugReportResponse, BugReportType, BugSeverity, ChecklistRun, ChecklistRunInput, ChecklistStepResult, ChecklistTask, CompensationRates, CompensationWallet, EarningsSummary, EndTesterSessionInput, EnrollmentResponse, KnowledgeBaseAnswer, KnowledgeBaseCitation, KnowledgeFile, KnowledgeFileSummary, LiveNoteInput, MoneyEntry, MoneyKind, MoneyMode, MoneyTotals, MyBugReportSummary, MyBugReportsResponse, NotificationsResult, PaidAssignment, PayoutRecord, PhoneConfirmResponse, PhoneStartResponse, PushRegistration, RegisterDeviceInput, RetestItem, RetestStepVerdicts, SdkUpdateInfo, SessionBreadcrumbInput, SessionBreadcrumbsResponse, SessionEventInput, SessionEventsResponse, StartTesterSessionInput, SubmissionResponse, TaskListFilter, TaskListResponse, TaskPreset, TaskStep, TesterDeviceResponse, TesterGateReason, TesterPoints, TesterProfile, TesterSessionEndReason, TesterSessionResponse, TesterTask, TpkNotification, WorkCommand, WorkState };
package/dist/index.js CHANGED
@@ -39,6 +39,12 @@ var import_axios = __toESM(require("axios"));
39
39
  var import_core = require("@testerpaykit/core");
40
40
  var TesterPayKitApiClient = class {
41
41
  constructor(config) {
42
+ /**
43
+ * Called on any 403 `phone_required` / `approval_required` answer: the
44
+ * tester is not (or no longer) cleared to report. SDKs hide their
45
+ * tester UI on it. The request still rejects as before.
46
+ */
47
+ this.onTesterGate = null;
42
48
  this.apiKey = config.apiKey;
43
49
  this.tokenManager = config.tokenManager || new import_core.TokenManager();
44
50
  this.client = import_axios.default.create({
@@ -67,6 +73,13 @@ var TesterPayKitApiClient = class {
67
73
  if (error.response?.status === 401) {
68
74
  this.tokenManager.clear();
69
75
  }
76
+ const code = error.response?.data?.error;
77
+ if (error.response?.status === 403 && (code === "phone_required" || code === "approval_required")) {
78
+ try {
79
+ this.onTesterGate?.(code);
80
+ } catch {
81
+ }
82
+ }
70
83
  return Promise.reject(error);
71
84
  }
72
85
  );
@@ -464,6 +477,47 @@ var TesterPayKitApiClient = class {
464
477
  );
465
478
  return response.data;
466
479
  }
480
+ /**
481
+ * POST /v1/testers/me/phone/start — sends a 6-digit SMS code.
482
+ * Throws with status 400 (invalid_phone), 429 (too_many_codes) or
483
+ * 503 (sms_not_configured: the server cannot send SMS yet).
484
+ */
485
+ async startPhoneVerification(phone) {
486
+ const response = await this.client.post(
487
+ "/v1/testers/me/phone/start",
488
+ { phone }
489
+ );
490
+ return response.data;
491
+ }
492
+ /**
493
+ * POST /v1/testers/me/phone/confirm — confirms the code. Returns the
494
+ * tester's handle; the same number on another install hands it over.
495
+ * `device` binds the number to this physical device (migration 077):
496
+ * a number already confirmed on another device throws 409
497
+ * `device_not_allowed` until an admin allows the new one.
498
+ */
499
+ async confirmPhoneVerification(verificationId, code, device) {
500
+ const response = await this.client.post(
501
+ "/v1/testers/me/phone/confirm",
502
+ { verificationId, code, ...device }
503
+ );
504
+ return response.data;
505
+ }
506
+ async getCompensation() {
507
+ return (await this.client.get("/v1/testers/me/compensation")).data;
508
+ }
509
+ async recordPaidWork(command) {
510
+ return (await this.client.post("/v1/testers/me/compensation", command)).data;
511
+ }
512
+ async registerCompensationPush(registration) {
513
+ await this.client.post("/v1/testers/me/compensation", { action: "push", ...registration });
514
+ }
515
+ async getPayoutAccount() {
516
+ return (await this.client.get("/v1/testers/me/payout-account")).data;
517
+ }
518
+ async createPayoutAccountLink() {
519
+ return (await this.client.post("/v1/testers/me/payout-account")).data;
520
+ }
467
521
  /** GET /v1/testers/me/points — current point balance + breakdown. */
468
522
  async getMyPoints() {
469
523
  const response = await this.client.get(
@@ -580,17 +634,6 @@ var TesterPayKitApiClient = class {
580
634
  );
581
635
  return response.data;
582
636
  }
583
- /**
584
- * POST /v1/session-feedback
585
- * Submit end-of-session feedback (rating, comments, etc.).
586
- */
587
- async submitSessionEndFeedback(payload) {
588
- const response = await this.client.post(
589
- "/v1/session-feedback",
590
- payload
591
- );
592
- return response.data;
593
- }
594
637
  /**
595
638
  * Upload an attachment directly (not tied to a specific bug report).
596
639
  * POST /v1/attachments — alternate path from the contract alongside
package/dist/index.mjs CHANGED
@@ -5,6 +5,12 @@ import {
5
5
  } from "@testerpaykit/core";
6
6
  var TesterPayKitApiClient = class {
7
7
  constructor(config) {
8
+ /**
9
+ * Called on any 403 `phone_required` / `approval_required` answer: the
10
+ * tester is not (or no longer) cleared to report. SDKs hide their
11
+ * tester UI on it. The request still rejects as before.
12
+ */
13
+ this.onTesterGate = null;
8
14
  this.apiKey = config.apiKey;
9
15
  this.tokenManager = config.tokenManager || new TokenManager();
10
16
  this.client = axios.create({
@@ -33,6 +39,13 @@ var TesterPayKitApiClient = class {
33
39
  if (error.response?.status === 401) {
34
40
  this.tokenManager.clear();
35
41
  }
42
+ const code = error.response?.data?.error;
43
+ if (error.response?.status === 403 && (code === "phone_required" || code === "approval_required")) {
44
+ try {
45
+ this.onTesterGate?.(code);
46
+ } catch {
47
+ }
48
+ }
36
49
  return Promise.reject(error);
37
50
  }
38
51
  );
@@ -430,6 +443,47 @@ var TesterPayKitApiClient = class {
430
443
  );
431
444
  return response.data;
432
445
  }
446
+ /**
447
+ * POST /v1/testers/me/phone/start — sends a 6-digit SMS code.
448
+ * Throws with status 400 (invalid_phone), 429 (too_many_codes) or
449
+ * 503 (sms_not_configured: the server cannot send SMS yet).
450
+ */
451
+ async startPhoneVerification(phone) {
452
+ const response = await this.client.post(
453
+ "/v1/testers/me/phone/start",
454
+ { phone }
455
+ );
456
+ return response.data;
457
+ }
458
+ /**
459
+ * POST /v1/testers/me/phone/confirm — confirms the code. Returns the
460
+ * tester's handle; the same number on another install hands it over.
461
+ * `device` binds the number to this physical device (migration 077):
462
+ * a number already confirmed on another device throws 409
463
+ * `device_not_allowed` until an admin allows the new one.
464
+ */
465
+ async confirmPhoneVerification(verificationId, code, device) {
466
+ const response = await this.client.post(
467
+ "/v1/testers/me/phone/confirm",
468
+ { verificationId, code, ...device }
469
+ );
470
+ return response.data;
471
+ }
472
+ async getCompensation() {
473
+ return (await this.client.get("/v1/testers/me/compensation")).data;
474
+ }
475
+ async recordPaidWork(command) {
476
+ return (await this.client.post("/v1/testers/me/compensation", command)).data;
477
+ }
478
+ async registerCompensationPush(registration) {
479
+ await this.client.post("/v1/testers/me/compensation", { action: "push", ...registration });
480
+ }
481
+ async getPayoutAccount() {
482
+ return (await this.client.get("/v1/testers/me/payout-account")).data;
483
+ }
484
+ async createPayoutAccountLink() {
485
+ return (await this.client.post("/v1/testers/me/payout-account")).data;
486
+ }
433
487
  /** GET /v1/testers/me/points — current point balance + breakdown. */
434
488
  async getMyPoints() {
435
489
  const response = await this.client.get(
@@ -546,17 +600,6 @@ var TesterPayKitApiClient = class {
546
600
  );
547
601
  return response.data;
548
602
  }
549
- /**
550
- * POST /v1/session-feedback
551
- * Submit end-of-session feedback (rating, comments, etc.).
552
- */
553
- async submitSessionEndFeedback(payload) {
554
- const response = await this.client.post(
555
- "/v1/session-feedback",
556
- payload
557
- );
558
- return response.data;
559
- }
560
603
  /**
561
604
  * Upload an attachment directly (not tied to a specific bug report).
562
605
  * POST /v1/attachments — alternate path from the contract alongside
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@testerpaykit/api-client",
3
- "version": "1.7.0",
3
+ "version": "2.0.0",
4
4
  "description": "API client for TesterPayKit backend",
5
5
  "main": "./dist/index.js",
6
6
  "module": "./dist/index.mjs",
@@ -1,4 +1,5 @@
1
1
  import axios, { AxiosInstance } from 'axios';
2
+ import type { CompensationWallet, PaidAssignment, WorkCommand, PushRegistration } from './compensation';
2
3
  import {
3
4
  IApiClient,
4
5
  LoginRequest,
@@ -70,11 +71,21 @@ export interface ApiClientConfig {
70
71
  * - Request/response interceptors for auth headers
71
72
  * - Integration with TokenManager for token lifecycle
72
73
  */
74
+ /** The tester gate's 403 codes (migrations 075 + 077). */
75
+ export type TesterGateReason = 'phone_required' | 'approval_required';
76
+
73
77
  export class TesterPayKitApiClient implements IApiClient {
74
78
  private client: AxiosInstance;
75
79
  private tokenManager: TokenManager;
76
80
  private apiKey: string;
77
81
 
82
+ /**
83
+ * Called on any 403 `phone_required` / `approval_required` answer: the
84
+ * tester is not (or no longer) cleared to report. SDKs hide their
85
+ * tester UI on it. The request still rejects as before.
86
+ */
87
+ onTesterGate: ((reason: TesterGateReason) => void) | null = null;
88
+
78
89
  constructor(config: ApiClientConfig) {
79
90
  this.apiKey = config.apiKey;
80
91
  this.tokenManager = config.tokenManager || new TokenManager();
@@ -111,6 +122,17 @@ export class TesterPayKitApiClient implements IApiClient {
111
122
  // Token expired or invalid, clear tokens
112
123
  this.tokenManager.clear();
113
124
  }
125
+ const code = error.response?.data?.error;
126
+ if (
127
+ error.response?.status === 403 &&
128
+ (code === 'phone_required' || code === 'approval_required')
129
+ ) {
130
+ try {
131
+ this.onTesterGate?.(code);
132
+ } catch {
133
+ // A listener problem must not change the request's outcome.
134
+ }
135
+ }
114
136
  return Promise.reject(error);
115
137
  }
116
138
  );
@@ -606,6 +628,58 @@ export class TesterPayKitApiClient implements IApiClient {
606
628
  return response.data;
607
629
  }
608
630
 
631
+ /**
632
+ * POST /v1/testers/me/phone/start — sends a 6-digit SMS code.
633
+ * Throws with status 400 (invalid_phone), 429 (too_many_codes) or
634
+ * 503 (sms_not_configured: the server cannot send SMS yet).
635
+ */
636
+ async startPhoneVerification(phone: string): Promise<PhoneStartResponse> {
637
+ const response = await this.client.post<PhoneStartResponse>(
638
+ '/v1/testers/me/phone/start',
639
+ { phone },
640
+ );
641
+ return response.data;
642
+ }
643
+
644
+ /**
645
+ * POST /v1/testers/me/phone/confirm — confirms the code. Returns the
646
+ * tester's handle; the same number on another install hands it over.
647
+ * `device` binds the number to this physical device (migration 077):
648
+ * a number already confirmed on another device throws 409
649
+ * `device_not_allowed` until an admin allows the new one.
650
+ */
651
+ async confirmPhoneVerification(
652
+ verificationId: string,
653
+ code: string,
654
+ device?: { deviceKey: string; platform: 'ios' | 'android' | 'web' },
655
+ ): Promise<PhoneConfirmResponse> {
656
+ const response = await this.client.post<PhoneConfirmResponse>(
657
+ '/v1/testers/me/phone/confirm',
658
+ { verificationId, code, ...device },
659
+ );
660
+ return response.data;
661
+ }
662
+
663
+ async getCompensation(): Promise<CompensationWallet> {
664
+ return (await this.client.get<CompensationWallet>('/v1/testers/me/compensation')).data;
665
+ }
666
+
667
+ async recordPaidWork(command: WorkCommand): Promise<PaidAssignment> {
668
+ return (await this.client.post<PaidAssignment>('/v1/testers/me/compensation', command)).data;
669
+ }
670
+
671
+ async registerCompensationPush(registration: PushRegistration): Promise<void> {
672
+ await this.client.post('/v1/testers/me/compensation', { action: 'push', ...registration });
673
+ }
674
+
675
+ async getPayoutAccount(): Promise<{ has_account: boolean; transfers_active: boolean; payments_configured: boolean }> {
676
+ return (await this.client.get('/v1/testers/me/payout-account')).data;
677
+ }
678
+
679
+ async createPayoutAccountLink(): Promise<{ url: string }> {
680
+ return (await this.client.post('/v1/testers/me/payout-account')).data;
681
+ }
682
+
609
683
  /** GET /v1/testers/me/points — current point balance + breakdown. */
610
684
  async getMyPoints(): Promise<TesterPoints> {
611
685
  const response = await this.client.get<TesterPoints>(
@@ -754,20 +828,6 @@ export class TesterPayKitApiClient implements IApiClient {
754
828
  return response.data;
755
829
  }
756
830
 
757
- /**
758
- * POST /v1/session-feedback
759
- * Submit end-of-session feedback (rating, comments, etc.).
760
- */
761
- async submitSessionEndFeedback(
762
- payload: Record<string, unknown>,
763
- ): Promise<FeedbackResponse> {
764
- const response = await this.client.post<FeedbackResponse>(
765
- '/v1/session-feedback',
766
- payload,
767
- );
768
- return response.data;
769
- }
770
-
771
831
  /**
772
832
  * Upload an attachment directly (not tied to a specific bug report).
773
833
  * POST /v1/attachments — alternate path from the contract alongside
@@ -1214,7 +1274,12 @@ export interface EnrollmentResponse {
1214
1274
  export interface TesterProfile {
1215
1275
  id: string;
1216
1276
  email?: string | null;
1277
+ /** System handle, e.g. "sad-banana" (migration 074). */
1217
1278
  handle?: string | null;
1279
+ /** True once this install confirmed a phone number. */
1280
+ phoneVerified?: boolean;
1281
+ /** True once an admin approved the person (migration 077). */
1282
+ approved?: boolean;
1218
1283
  fullName?: string | null;
1219
1284
  rating?: number | null;
1220
1285
  pointsTotal?: number | null;
@@ -1222,6 +1287,20 @@ export interface TesterProfile {
1222
1287
  createdAt?: string;
1223
1288
  }
1224
1289
 
1290
+ export interface PhoneStartResponse {
1291
+ verificationId: string;
1292
+ expiresInSeconds: number;
1293
+ /** Only returned by a development server. */
1294
+ devCode?: string;
1295
+ }
1296
+
1297
+ export interface PhoneConfirmResponse {
1298
+ handle: string;
1299
+ phoneVerified: boolean;
1300
+ /** Tester status after the confirmation (e.g. `active`, `pending`). */
1301
+ status?: string | null;
1302
+ }
1303
+
1225
1304
  export interface TesterPoints {
1226
1305
  total: number;
1227
1306
  breakdown?: Record<string, number>;
@@ -1284,13 +1363,6 @@ export interface TesterDeviceResponse {
1284
1363
  deviceType: string;
1285
1364
  }
1286
1365
 
1287
- /** Response from POST /v1/session-feedback */
1288
- export interface FeedbackResponse {
1289
- id: string;
1290
- status: string;
1291
- message?: string;
1292
- }
1293
-
1294
1366
  function stepResults(verdicts: RetestStepVerdicts): { step: number; passed: boolean }[] {
1295
1367
  return Object.entries(verdicts).map(([step, passed]) => ({ step: Number(step), passed }));
1296
1368
  }
@@ -0,0 +1,59 @@
1
+ /** `play` = play money in the pilot: real ledger rows, never a payout.
2
+ * Every UI labels such amounts "Spielgeld · Pilot" / "Play money · pilot". */
3
+ export type MoneyMode = 'play' | 'test' | 'live';
4
+ export type WorkState = 'offered' | 'active' | 'paused' | 'review' | 'disputed' | 'approved' | 'cancelled';
5
+ export interface PaidAssignment {
6
+ id: string; project_id: string; tester_id: string; title: string; project_name: string;
7
+ mode: MoneyMode; terms_version: 1; rate_cents: number; minimum_cents: number;
8
+ budget_cents: number; seconds: number; running_since: string | null;
9
+ state: WorkState; revision: number; amount_cents: number | null;
10
+ review_due: string | null; review_note: string | null; completion_note: string | null;
11
+ }
12
+ /** time = paid assignment · task = checklist task on its announced time ·
13
+ * bonus = idea bonus · bug_bonus · reproduction · retest (one per round). */
14
+ export type MoneyKind = 'time' | 'task' | 'bonus' | 'bug_bonus' | 'reproduction' | 'retest' | 'start_bonus';
15
+ export interface MoneyEntry {
16
+ id: string; project_id: string; project_name: string; tester_id: string; mode: MoneyMode;
17
+ kind: MoneyKind; reason: string; amount_cents: number; currency: 'eur';
18
+ /** review = waits for the 3-working-day window, then released. */
19
+ status: 'review' | 'approved' | 'processing' | 'transferred' | 'held';
20
+ units: number; review_due: string | null; review_note: string | null;
21
+ bug_id: string | null; task_preset_id: string | null;
22
+ created_at: string; transfer_id: string | null;
23
+ }
24
+ /** Sums in the current mode, in cents. Bonuses never count towards the 5 € floor. */
25
+ export interface MoneyTotals {
26
+ in_review_cents: number; released_cents: number; bonus_cents: number;
27
+ held_cents: number; total_cents: number;
28
+ }
29
+ export interface CompensationRates {
30
+ rate_cents_per_minute: number; minimum_cents: number;
31
+ bug_bonus_cents: { easy: number; medium: number; hard: number };
32
+ reproduction_cents: number; retest_per_fix_cents: number; retest_round_minimum_cents: number;
33
+ idea_bonus_choices_cents: number[]; review_working_days: number;
34
+ /** Start bonus, booked once per person on the first phone confirmation. */
35
+ start_bonus_cents?: number;
36
+ }
37
+ export interface CompensationWallet {
38
+ /** Current mode; `play` = label every amount as play money. */
39
+ mode: MoneyMode;
40
+ currency: 'eur'; server_time: string; rates: CompensationRates;
41
+ /** The person = every app install with the same confirmed phone. */
42
+ person: { handle: string | null; phone_confirmed: boolean; tester_count: number;
43
+ apps: Array<{ project_id: string; project_name: string }> };
44
+ /** Whole person across apps … */
45
+ totals: MoneyTotals;
46
+ /** … and the share of this app install. */
47
+ this_app: MoneyTotals;
48
+ assignments: PaidAssignment[]; entries: MoneyEntry[];
49
+ balances: Record<MoneyMode, Record<MoneyEntry['status'], number>>;
50
+ legacy: Array<{ id: string; source: string; amount_cents: number; status: string }>;
51
+ }
52
+ export interface WorkCommand {
53
+ assignment_id: string; request_id: string; revision: number;
54
+ action: 'start' | 'pause' | 'submit' | 'submit_partial' | 'decline';
55
+ accept_terms_version?: 1; seconds?: number; note?: string;
56
+ }
57
+ export interface PushRegistration {
58
+ installation_id: string; app_id: string; token?: string; enabled: boolean;
59
+ }
package/src/index.ts CHANGED
@@ -1 +1,2 @@
1
1
  export * from './TesterPayKitApiClient';
2
+ export * from './compensation';
@@ -72,6 +72,29 @@ describe('TesterPayKitApiClient', () => {
72
72
  });
73
73
  });
74
74
 
75
+ describe('onTesterGate', () => {
76
+ function rejectWith(status: number, error?: string) {
77
+ const onError = mockAxiosInstance.interceptors.response.use.mock.calls[0][1];
78
+ return onError({ response: { status, data: error ? { error } : {} } });
79
+ }
80
+
81
+ it('reports a 403 phone_required / approval_required and still rejects', async () => {
82
+ const seen: string[] = [];
83
+ client.onTesterGate = (reason) => seen.push(reason);
84
+ await expect(rejectWith(403, 'phone_required')).rejects.toBeTruthy();
85
+ await expect(rejectWith(403, 'approval_required')).rejects.toBeTruthy();
86
+ expect(seen).toEqual(['phone_required', 'approval_required']);
87
+ });
88
+
89
+ it('ignores other errors', async () => {
90
+ const seen: string[] = [];
91
+ client.onTesterGate = (reason) => seen.push(reason);
92
+ await expect(rejectWith(403, 'forbidden')).rejects.toBeTruthy();
93
+ await expect(rejectWith(500)).rejects.toBeTruthy();
94
+ expect(seen).toEqual([]);
95
+ });
96
+ });
97
+
75
98
  describe('login', () => {
76
99
  it('should successfully login and store tokens', async () => {
77
100
  const loginRequest = {