@testerpaykit/api-client 2.0.0 → 3.2.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,37 @@
2
2
 
3
3
  All notable changes to `@testerpaykit/api-client` are documented here.
4
4
 
5
+ ## 3.2.0 — 2026-11-18
6
+
7
+ ### Added
8
+ - `getPersonas(projectId)` → `{ current, persona, personas }` or `null` on
9
+ 404, and `setPersona({ projectId, personaId })` (`null` = "Myself"):
10
+ test personas of "Login with TPK" (GET/PUT `/v1/testers/me/personas`).
11
+ Types `TesterPersona`, `TesterPersonaList`, `TesterPersonaText`.
12
+
13
+ ## 3.1.0 — 2026-11-14
14
+
15
+ ### Added
16
+ - `clientHeader` in `ApiClientConfig`: sent as `X-TPK-Client` on every
17
+ request (e.g. `expo/2.2.0`). Default none.
18
+ - Version check: on a 426 `client_outdated` answer the client calls
19
+ `onClientOutdated(info)` once, `clientOutdated` holds the info, and every
20
+ later request rejects with `ClientOutdatedError` before it reaches the
21
+ network (no `response`, so retry queues keep their work).
22
+ `markClientOutdated(info)` blocks a client created later in the same run.
23
+ Also exported: `TPK_CLIENT_HEADER`, `parseClientOutdated`, the
24
+ `ClientOutdatedInfo` type.
25
+
26
+ ## 3.0.0 — 2026-11-10
27
+
28
+ Breaking: `startPhoneVerification`, `confirmPhoneVerification` and their types
29
+ removed. Testers confirm their number once in the TPK app (decision
30
+ 2026-11-10).
31
+
32
+ ### Added
33
+ - `createAppLink({ projectId, platform })` → `{ code, url, appUrl, expiresAt }`:
34
+ a short-lived code for confirming this install in the TPK app.
35
+
5
36
  ## 2.0.0 — 2026-11-07
6
37
 
7
38
  Breaking: `submitSessionEndFeedback` removed.
package/dist/index.d.mts CHANGED
@@ -162,7 +162,37 @@ interface ApiClientConfig {
162
162
  baseURL?: string;
163
163
  apiKey: string;
164
164
  tokenManager?: TokenManager;
165
+ /**
166
+ * Sent as `X-TPK-Client` on every request, e.g. `expo/2.2.0` (decision
167
+ * 2026-11-14 "Mindestversion je Client-Art"). Default none: the server
168
+ * then serves the request without a version check.
169
+ */
170
+ clientHeader?: string;
171
+ }
172
+ /** Request header a client identifies itself with (`<kind>/<version>`). */
173
+ declare const TPK_CLIENT_HEADER = "X-TPK-Client";
174
+ /** Body of a 426 `client_outdated` answer: this client is below the
175
+ * minimum version the server still serves. Fields are null when the
176
+ * request carried no `X-TPK-Client`. */
177
+ interface ClientOutdatedInfo {
178
+ kind: string | null;
179
+ min: string | null;
180
+ yours: string | null;
181
+ message: string | null;
182
+ }
183
+ /**
184
+ * Thrown instead of sending, for every request after a 426
185
+ * `client_outdated` (see `TesterPayKitApiClient.clientOutdated`). It has
186
+ * no `response`, so callers that retry on network errors keep their
187
+ * queued work for a newer build instead of dropping it.
188
+ */
189
+ declare class ClientOutdatedError extends Error {
190
+ readonly info: ClientOutdatedInfo;
191
+ readonly code = "TPK_CLIENT_OUTDATED";
192
+ constructor(info: ClientOutdatedInfo);
165
193
  }
194
+ /** The `client_outdated` body of a 426 answer, else null. */
195
+ declare function parseClientOutdated(status: number | undefined, body: unknown): ClientOutdatedInfo | null;
166
196
  /**
167
197
  * TesterPayKit API Client implementation using Axios.
168
198
  *
@@ -183,6 +213,20 @@ declare class TesterPayKitApiClient implements IApiClient {
183
213
  * tester UI on it. The request still rejects as before.
184
214
  */
185
215
  onTesterGate: ((reason: TesterGateReason) => void) | null;
216
+ /**
217
+ * Called once, on the first 426 `client_outdated` answer. From then on
218
+ * this client sends nothing: every request rejects with
219
+ * [ClientOutdatedError] before it reaches the network.
220
+ */
221
+ onClientOutdated: ((info: ClientOutdatedInfo) => void) | null;
222
+ private outdated;
223
+ /** Set after a 426 `client_outdated`; null while the server serves us. */
224
+ get clientOutdated(): ClientOutdatedInfo | null;
225
+ /**
226
+ * Blocks this client as if it had received the 426 itself (an earlier
227
+ * client in the same app run did). Does not call [onClientOutdated].
228
+ */
229
+ markClientOutdated(info: ClientOutdatedInfo): void;
186
230
  constructor(config: ApiClientConfig);
187
231
  /**
188
232
  * Setup request/response interceptors for JWT authentication.
@@ -389,22 +433,34 @@ declare class TesterPayKitApiClient implements IApiClient {
389
433
  */
390
434
  getMyProfile(): Promise<TesterProfile>;
391
435
  /**
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).
436
+ * POST /v1/testers/me/phone/link — a short-lived code for confirming this
437
+ * install in the TPK app (decision 2026-11-10, replaces the SMS dialog).
438
+ * Open `appUrl` (TPK app installed) or `url` (web page with an install
439
+ * hint); the person allows it there, then GET /v1/testers/me/profile
440
+ * reports the install as confirmed.
395
441
  */
396
- startPhoneVerification(phone: string): Promise<PhoneStartResponse>;
442
+ createAppLink(input: {
443
+ projectId?: string;
444
+ platform?: 'ios' | 'android' | 'web';
445
+ }): Promise<AppLinkResponse>;
446
+ /**
447
+ * The test personas of a project and the tester's current choice
448
+ * (GET /v1/testers/me/personas?project_id=). Suggested personas come
449
+ * first; `current` null = "Myself". A 404 (the tester is not in the
450
+ * project yet) yields null: skip the picker silently.
451
+ */
452
+ getPersonas(projectId: string): Promise<TesterPersonaList | null>;
397
453
  /**
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.
454
+ * The tester picks a persona (PUT /v1/testers/me/personas);
455
+ * `personaId` null = "Myself". New sessions and reports carry it.
403
456
  */
404
- confirmPhoneVerification(verificationId: string, code: string, device?: {
405
- deviceKey: string;
406
- platform: 'ios' | 'android' | 'web';
407
- }): Promise<PhoneConfirmResponse>;
457
+ setPersona(input: {
458
+ projectId: string;
459
+ personaId: string | null;
460
+ }): Promise<{
461
+ current: string | null;
462
+ persona: TesterPersona | null;
463
+ }>;
408
464
  getCompensation(): Promise<CompensationWallet>;
409
465
  recordPaidWork(command: WorkCommand): Promise<PaidAssignment>;
410
466
  registerCompensationPush(registration: PushRegistration): Promise<void>;
@@ -468,7 +524,7 @@ declare class TesterPayKitApiClient implements IApiClient {
468
524
  *
469
525
  * RAG over the project's knowledge-base markdown files. Embeds the
470
526
  * question, retrieves top-K nearest chunks via pgvector cosine
471
- * similarity, and asks gpt-4o-mini to synthesise an answer that
527
+ * similarity, and asks gpt-6-luna to synthesise an answer that
472
528
  * STRICTLY cites those chunks. Answer language tracks the
473
529
  * question (English / German).
474
530
  *
@@ -520,7 +576,7 @@ declare class TesterPayKitApiClient implements IApiClient {
520
576
  * Contract: wire.bug_reports.voiceExtractBugFields
521
577
  *
522
578
  * Sends base64-encoded audio to the server. The server runs Whisper
523
- * (transcription) + gpt-4o-mini (structured extraction) and returns
579
+ * (transcription) + gpt-6-luna (structured extraction) and returns
524
580
  * pre-filled bug-report fields in the tester's language.
525
581
  *
526
582
  * Wire body uses snake_case per contract. Timeout is 60 s because
@@ -558,7 +614,7 @@ interface KnowledgeBaseAnswer {
558
614
  citations: KnowledgeBaseCitation[];
559
615
  /** Resolved project UUID — useful for telemetry / dedup. */
560
616
  projectId: string;
561
- /** Echo of the model used for the answer (e.g. "gpt-4o-mini"). */
617
+ /** Echo of the model used for the answer (e.g. "gpt-6-luna"). */
562
618
  model?: string;
563
619
  }
564
620
  interface KnowledgeBaseCitation {
@@ -827,17 +883,42 @@ interface TesterProfile {
827
883
  status?: string;
828
884
  createdAt?: string;
829
885
  }
830
- interface PhoneStartResponse {
831
- verificationId: string;
832
- expiresInSeconds: number;
833
- /** Only returned by a development server. */
834
- devCode?: string;
886
+ interface AppLinkResponse {
887
+ code: string;
888
+ /** Web page: opens the TPK app via universal link, else an install hint. */
889
+ url: string;
890
+ /** testerpaykit://link/<code>, opens the TPK app directly. */
891
+ appUrl: string;
892
+ expiresAt: string;
893
+ }
894
+ /** A text in both UI languages. */
895
+ interface TesterPersonaText {
896
+ de: string;
897
+ en: string;
898
+ }
899
+ /** One test persona (made-up data; never real data of the tester). */
900
+ interface TesterPersona {
901
+ id: string;
902
+ /** True for a persona the developer made for this project. */
903
+ own: boolean;
904
+ slug?: string | null;
905
+ title: TesterPersonaText;
906
+ sub: TesterPersonaText;
907
+ briefing: TesterPersonaText;
908
+ watch: {
909
+ de: string[];
910
+ en: string[];
911
+ };
912
+ attributes: Record<string, unknown>;
913
+ /** The developer suggested it (those come first). */
914
+ suggested?: boolean;
835
915
  }
836
- interface PhoneConfirmResponse {
837
- handle: string;
838
- phoneVerified: boolean;
839
- /** Tester status after the confirmation (e.g. `active`, `pending`). */
840
- status?: string | null;
916
+ /** Answer of GET /v1/testers/me/personas. */
917
+ interface TesterPersonaList {
918
+ /** The chosen persona id; null = "Myself". */
919
+ current: string | null;
920
+ persona: TesterPersona | null;
921
+ personas: TesterPersona[];
841
922
  }
842
923
  interface TesterPoints {
843
924
  total: number;
@@ -943,5 +1024,5 @@ interface TaskStep {
943
1024
  estimatedMinutes?: number | null;
944
1025
  }
945
1026
 
946
- export { TesterPayKitApiClient };
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 };
1027
+ export { ClientOutdatedError, TPK_CLIENT_HEADER, TesterPayKitApiClient, parseClientOutdated };
1028
+ export type { AnonymousLoginResponse, ApiClientConfig, AppLinkResponse, BugCategory, BugReportAttachmentInput, BugReportAttachmentResponse, BugReportPayload, BugReportResponse, BugReportType, BugSeverity, ChecklistRun, ChecklistRunInput, ChecklistStepResult, ChecklistTask, ClientOutdatedInfo, CompensationRates, CompensationWallet, EarningsSummary, EndTesterSessionInput, EnrollmentResponse, KnowledgeBaseAnswer, KnowledgeBaseCitation, KnowledgeFile, KnowledgeFileSummary, LiveNoteInput, MoneyEntry, MoneyKind, MoneyMode, MoneyTotals, MyBugReportSummary, MyBugReportsResponse, NotificationsResult, PaidAssignment, PayoutRecord, PushRegistration, RegisterDeviceInput, RetestItem, RetestStepVerdicts, SdkUpdateInfo, SessionBreadcrumbInput, SessionBreadcrumbsResponse, SessionEventInput, SessionEventsResponse, StartTesterSessionInput, SubmissionResponse, TaskListFilter, TaskListResponse, TaskPreset, TaskStep, TesterDeviceResponse, TesterGateReason, TesterPersona, TesterPersonaList, TesterPersonaText, TesterPoints, TesterProfile, TesterSessionEndReason, TesterSessionResponse, TesterTask, TpkNotification, WorkCommand, WorkState };
package/dist/index.d.ts CHANGED
@@ -162,7 +162,37 @@ interface ApiClientConfig {
162
162
  baseURL?: string;
163
163
  apiKey: string;
164
164
  tokenManager?: TokenManager;
165
+ /**
166
+ * Sent as `X-TPK-Client` on every request, e.g. `expo/2.2.0` (decision
167
+ * 2026-11-14 "Mindestversion je Client-Art"). Default none: the server
168
+ * then serves the request without a version check.
169
+ */
170
+ clientHeader?: string;
171
+ }
172
+ /** Request header a client identifies itself with (`<kind>/<version>`). */
173
+ declare const TPK_CLIENT_HEADER = "X-TPK-Client";
174
+ /** Body of a 426 `client_outdated` answer: this client is below the
175
+ * minimum version the server still serves. Fields are null when the
176
+ * request carried no `X-TPK-Client`. */
177
+ interface ClientOutdatedInfo {
178
+ kind: string | null;
179
+ min: string | null;
180
+ yours: string | null;
181
+ message: string | null;
182
+ }
183
+ /**
184
+ * Thrown instead of sending, for every request after a 426
185
+ * `client_outdated` (see `TesterPayKitApiClient.clientOutdated`). It has
186
+ * no `response`, so callers that retry on network errors keep their
187
+ * queued work for a newer build instead of dropping it.
188
+ */
189
+ declare class ClientOutdatedError extends Error {
190
+ readonly info: ClientOutdatedInfo;
191
+ readonly code = "TPK_CLIENT_OUTDATED";
192
+ constructor(info: ClientOutdatedInfo);
165
193
  }
194
+ /** The `client_outdated` body of a 426 answer, else null. */
195
+ declare function parseClientOutdated(status: number | undefined, body: unknown): ClientOutdatedInfo | null;
166
196
  /**
167
197
  * TesterPayKit API Client implementation using Axios.
168
198
  *
@@ -183,6 +213,20 @@ declare class TesterPayKitApiClient implements IApiClient {
183
213
  * tester UI on it. The request still rejects as before.
184
214
  */
185
215
  onTesterGate: ((reason: TesterGateReason) => void) | null;
216
+ /**
217
+ * Called once, on the first 426 `client_outdated` answer. From then on
218
+ * this client sends nothing: every request rejects with
219
+ * [ClientOutdatedError] before it reaches the network.
220
+ */
221
+ onClientOutdated: ((info: ClientOutdatedInfo) => void) | null;
222
+ private outdated;
223
+ /** Set after a 426 `client_outdated`; null while the server serves us. */
224
+ get clientOutdated(): ClientOutdatedInfo | null;
225
+ /**
226
+ * Blocks this client as if it had received the 426 itself (an earlier
227
+ * client in the same app run did). Does not call [onClientOutdated].
228
+ */
229
+ markClientOutdated(info: ClientOutdatedInfo): void;
186
230
  constructor(config: ApiClientConfig);
187
231
  /**
188
232
  * Setup request/response interceptors for JWT authentication.
@@ -389,22 +433,34 @@ declare class TesterPayKitApiClient implements IApiClient {
389
433
  */
390
434
  getMyProfile(): Promise<TesterProfile>;
391
435
  /**
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).
436
+ * POST /v1/testers/me/phone/link — a short-lived code for confirming this
437
+ * install in the TPK app (decision 2026-11-10, replaces the SMS dialog).
438
+ * Open `appUrl` (TPK app installed) or `url` (web page with an install
439
+ * hint); the person allows it there, then GET /v1/testers/me/profile
440
+ * reports the install as confirmed.
395
441
  */
396
- startPhoneVerification(phone: string): Promise<PhoneStartResponse>;
442
+ createAppLink(input: {
443
+ projectId?: string;
444
+ platform?: 'ios' | 'android' | 'web';
445
+ }): Promise<AppLinkResponse>;
446
+ /**
447
+ * The test personas of a project and the tester's current choice
448
+ * (GET /v1/testers/me/personas?project_id=). Suggested personas come
449
+ * first; `current` null = "Myself". A 404 (the tester is not in the
450
+ * project yet) yields null: skip the picker silently.
451
+ */
452
+ getPersonas(projectId: string): Promise<TesterPersonaList | null>;
397
453
  /**
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.
454
+ * The tester picks a persona (PUT /v1/testers/me/personas);
455
+ * `personaId` null = "Myself". New sessions and reports carry it.
403
456
  */
404
- confirmPhoneVerification(verificationId: string, code: string, device?: {
405
- deviceKey: string;
406
- platform: 'ios' | 'android' | 'web';
407
- }): Promise<PhoneConfirmResponse>;
457
+ setPersona(input: {
458
+ projectId: string;
459
+ personaId: string | null;
460
+ }): Promise<{
461
+ current: string | null;
462
+ persona: TesterPersona | null;
463
+ }>;
408
464
  getCompensation(): Promise<CompensationWallet>;
409
465
  recordPaidWork(command: WorkCommand): Promise<PaidAssignment>;
410
466
  registerCompensationPush(registration: PushRegistration): Promise<void>;
@@ -468,7 +524,7 @@ declare class TesterPayKitApiClient implements IApiClient {
468
524
  *
469
525
  * RAG over the project's knowledge-base markdown files. Embeds the
470
526
  * question, retrieves top-K nearest chunks via pgvector cosine
471
- * similarity, and asks gpt-4o-mini to synthesise an answer that
527
+ * similarity, and asks gpt-6-luna to synthesise an answer that
472
528
  * STRICTLY cites those chunks. Answer language tracks the
473
529
  * question (English / German).
474
530
  *
@@ -520,7 +576,7 @@ declare class TesterPayKitApiClient implements IApiClient {
520
576
  * Contract: wire.bug_reports.voiceExtractBugFields
521
577
  *
522
578
  * Sends base64-encoded audio to the server. The server runs Whisper
523
- * (transcription) + gpt-4o-mini (structured extraction) and returns
579
+ * (transcription) + gpt-6-luna (structured extraction) and returns
524
580
  * pre-filled bug-report fields in the tester's language.
525
581
  *
526
582
  * Wire body uses snake_case per contract. Timeout is 60 s because
@@ -558,7 +614,7 @@ interface KnowledgeBaseAnswer {
558
614
  citations: KnowledgeBaseCitation[];
559
615
  /** Resolved project UUID — useful for telemetry / dedup. */
560
616
  projectId: string;
561
- /** Echo of the model used for the answer (e.g. "gpt-4o-mini"). */
617
+ /** Echo of the model used for the answer (e.g. "gpt-6-luna"). */
562
618
  model?: string;
563
619
  }
564
620
  interface KnowledgeBaseCitation {
@@ -827,17 +883,42 @@ interface TesterProfile {
827
883
  status?: string;
828
884
  createdAt?: string;
829
885
  }
830
- interface PhoneStartResponse {
831
- verificationId: string;
832
- expiresInSeconds: number;
833
- /** Only returned by a development server. */
834
- devCode?: string;
886
+ interface AppLinkResponse {
887
+ code: string;
888
+ /** Web page: opens the TPK app via universal link, else an install hint. */
889
+ url: string;
890
+ /** testerpaykit://link/<code>, opens the TPK app directly. */
891
+ appUrl: string;
892
+ expiresAt: string;
893
+ }
894
+ /** A text in both UI languages. */
895
+ interface TesterPersonaText {
896
+ de: string;
897
+ en: string;
898
+ }
899
+ /** One test persona (made-up data; never real data of the tester). */
900
+ interface TesterPersona {
901
+ id: string;
902
+ /** True for a persona the developer made for this project. */
903
+ own: boolean;
904
+ slug?: string | null;
905
+ title: TesterPersonaText;
906
+ sub: TesterPersonaText;
907
+ briefing: TesterPersonaText;
908
+ watch: {
909
+ de: string[];
910
+ en: string[];
911
+ };
912
+ attributes: Record<string, unknown>;
913
+ /** The developer suggested it (those come first). */
914
+ suggested?: boolean;
835
915
  }
836
- interface PhoneConfirmResponse {
837
- handle: string;
838
- phoneVerified: boolean;
839
- /** Tester status after the confirmation (e.g. `active`, `pending`). */
840
- status?: string | null;
916
+ /** Answer of GET /v1/testers/me/personas. */
917
+ interface TesterPersonaList {
918
+ /** The chosen persona id; null = "Myself". */
919
+ current: string | null;
920
+ persona: TesterPersona | null;
921
+ personas: TesterPersona[];
841
922
  }
842
923
  interface TesterPoints {
843
924
  total: number;
@@ -943,5 +1024,5 @@ interface TaskStep {
943
1024
  estimatedMinutes?: number | null;
944
1025
  }
945
1026
 
946
- export { TesterPayKitApiClient };
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 };
1027
+ export { ClientOutdatedError, TPK_CLIENT_HEADER, TesterPayKitApiClient, parseClientOutdated };
1028
+ export type { AnonymousLoginResponse, ApiClientConfig, AppLinkResponse, BugCategory, BugReportAttachmentInput, BugReportAttachmentResponse, BugReportPayload, BugReportResponse, BugReportType, BugSeverity, ChecklistRun, ChecklistRunInput, ChecklistStepResult, ChecklistTask, ClientOutdatedInfo, CompensationRates, CompensationWallet, EarningsSummary, EndTesterSessionInput, EnrollmentResponse, KnowledgeBaseAnswer, KnowledgeBaseCitation, KnowledgeFile, KnowledgeFileSummary, LiveNoteInput, MoneyEntry, MoneyKind, MoneyMode, MoneyTotals, MyBugReportSummary, MyBugReportsResponse, NotificationsResult, PaidAssignment, PayoutRecord, PushRegistration, RegisterDeviceInput, RetestItem, RetestStepVerdicts, SdkUpdateInfo, SessionBreadcrumbInput, SessionBreadcrumbsResponse, SessionEventInput, SessionEventsResponse, StartTesterSessionInput, SubmissionResponse, TaskListFilter, TaskListResponse, TaskPreset, TaskStep, TesterDeviceResponse, TesterGateReason, TesterPersona, TesterPersonaList, TesterPersonaText, TesterPoints, TesterProfile, TesterSessionEndReason, TesterSessionResponse, TesterTask, TpkNotification, WorkCommand, WorkState };
package/dist/index.js CHANGED
@@ -30,13 +30,32 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
30
30
  // src/index.ts
31
31
  var index_exports = {};
32
32
  __export(index_exports, {
33
- TesterPayKitApiClient: () => TesterPayKitApiClient
33
+ ClientOutdatedError: () => ClientOutdatedError,
34
+ TPK_CLIENT_HEADER: () => TPK_CLIENT_HEADER,
35
+ TesterPayKitApiClient: () => TesterPayKitApiClient,
36
+ parseClientOutdated: () => parseClientOutdated
34
37
  });
35
38
  module.exports = __toCommonJS(index_exports);
36
39
 
37
40
  // src/TesterPayKitApiClient.ts
38
41
  var import_axios = __toESM(require("axios"));
39
42
  var import_core = require("@testerpaykit/core");
43
+ var TPK_CLIENT_HEADER = "X-TPK-Client";
44
+ var ClientOutdatedError = class extends Error {
45
+ constructor(info) {
46
+ super(info.message ?? "TesterPayKit client is too old for the server.");
47
+ this.info = info;
48
+ this.code = "TPK_CLIENT_OUTDATED";
49
+ this.name = "ClientOutdatedError";
50
+ }
51
+ };
52
+ function parseClientOutdated(status, body) {
53
+ if (status !== 426 || typeof body !== "object" || body === null) return null;
54
+ const b = body;
55
+ if (b.error !== "client_outdated") return null;
56
+ const str = (v) => typeof v === "string" ? v : null;
57
+ return { kind: str(b.kind), min: str(b.min), yours: str(b.yours), message: str(b.message) };
58
+ }
40
59
  var TesterPayKitApiClient = class {
41
60
  constructor(config) {
42
61
  /**
@@ -45,22 +64,43 @@ var TesterPayKitApiClient = class {
45
64
  * tester UI on it. The request still rejects as before.
46
65
  */
47
66
  this.onTesterGate = null;
67
+ /**
68
+ * Called once, on the first 426 `client_outdated` answer. From then on
69
+ * this client sends nothing: every request rejects with
70
+ * [ClientOutdatedError] before it reaches the network.
71
+ */
72
+ this.onClientOutdated = null;
73
+ this.outdated = null;
48
74
  this.apiKey = config.apiKey;
49
75
  this.tokenManager = config.tokenManager || new import_core.TokenManager();
76
+ const headers = {
77
+ "Content-Type": "application/json",
78
+ "X-API-Key": this.apiKey
79
+ };
80
+ if (config.clientHeader) headers[TPK_CLIENT_HEADER] = config.clientHeader;
50
81
  this.client = import_axios.default.create({
51
82
  baseURL: config.baseURL || "https://api.testerpaykit.com",
52
- headers: {
53
- "Content-Type": "application/json",
54
- "X-API-Key": this.apiKey
55
- }
83
+ headers
56
84
  });
57
85
  this.setupInterceptors();
58
86
  }
87
+ /** Set after a 426 `client_outdated`; null while the server serves us. */
88
+ get clientOutdated() {
89
+ return this.outdated;
90
+ }
91
+ /**
92
+ * Blocks this client as if it had received the 426 itself (an earlier
93
+ * client in the same app run did). Does not call [onClientOutdated].
94
+ */
95
+ markClientOutdated(info) {
96
+ this.outdated ?? (this.outdated = info);
97
+ }
59
98
  /**
60
99
  * Setup request/response interceptors for JWT authentication.
61
100
  */
62
101
  setupInterceptors() {
63
102
  this.client.interceptors.request.use(async (config) => {
103
+ if (this.outdated) throw new ClientOutdatedError(this.outdated);
64
104
  const token = await this.tokenManager.ensureValidToken();
65
105
  if (token) {
66
106
  config.headers.Authorization = `Bearer ${token}`;
@@ -73,6 +113,14 @@ var TesterPayKitApiClient = class {
73
113
  if (error.response?.status === 401) {
74
114
  this.tokenManager.clear();
75
115
  }
116
+ const outdated = parseClientOutdated(error.response?.status, error.response?.data);
117
+ if (outdated && !this.outdated) {
118
+ this.outdated = outdated;
119
+ try {
120
+ this.onClientOutdated?.(outdated);
121
+ } catch {
122
+ }
123
+ }
76
124
  const code = error.response?.data?.error;
77
125
  if (error.response?.status === 403 && (code === "phone_required" || code === "approval_required")) {
78
126
  try {
@@ -478,30 +526,48 @@ var TesterPayKitApiClient = class {
478
526
  return response.data;
479
527
  }
480
528
  /**
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).
529
+ * POST /v1/testers/me/phone/link — a short-lived code for confirming this
530
+ * install in the TPK app (decision 2026-11-10, replaces the SMS dialog).
531
+ * Open `appUrl` (TPK app installed) or `url` (web page with an install
532
+ * hint); the person allows it there, then GET /v1/testers/me/profile
533
+ * reports the install as confirmed.
484
534
  */
485
- async startPhoneVerification(phone) {
535
+ async createAppLink(input) {
486
536
  const response = await this.client.post(
487
- "/v1/testers/me/phone/start",
488
- { phone }
537
+ "/v1/testers/me/phone/link",
538
+ input
489
539
  );
490
540
  return response.data;
491
541
  }
492
542
  /**
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.
543
+ * The test personas of a project and the tester's current choice
544
+ * (GET /v1/testers/me/personas?project_id=). Suggested personas come
545
+ * first; `current` null = "Myself". A 404 (the tester is not in the
546
+ * project yet) yields null: skip the picker silently.
498
547
  */
499
- async confirmPhoneVerification(verificationId, code, device) {
500
- const response = await this.client.post(
501
- "/v1/testers/me/phone/confirm",
502
- { verificationId, code, ...device }
548
+ async getPersonas(projectId) {
549
+ try {
550
+ const response = await this.client.get("/v1/testers/me/personas", {
551
+ params: { project_id: projectId }
552
+ });
553
+ const data = response.data;
554
+ if (!data || !Array.isArray(data.personas)) return null;
555
+ return { current: data.current ?? null, persona: data.persona ?? null, personas: data.personas };
556
+ } catch (e) {
557
+ if (e?.response?.status === 404) return null;
558
+ throw e;
559
+ }
560
+ }
561
+ /**
562
+ * The tester picks a persona (PUT /v1/testers/me/personas);
563
+ * `personaId` null = "Myself". New sessions and reports carry it.
564
+ */
565
+ async setPersona(input) {
566
+ const response = await this.client.put(
567
+ "/v1/testers/me/personas",
568
+ { project_id: input.projectId, persona_id: input.personaId }
503
569
  );
504
- return response.data;
570
+ return { current: response.data?.current ?? null, persona: response.data?.persona ?? null };
505
571
  }
506
572
  async getCompensation() {
507
573
  return (await this.client.get("/v1/testers/me/compensation")).data;
@@ -590,7 +656,7 @@ var TesterPayKitApiClient = class {
590
656
  *
591
657
  * RAG over the project's knowledge-base markdown files. Embeds the
592
658
  * question, retrieves top-K nearest chunks via pgvector cosine
593
- * similarity, and asks gpt-4o-mini to synthesise an answer that
659
+ * similarity, and asks gpt-6-luna to synthesise an answer that
594
660
  * STRICTLY cites those chunks. Answer language tracks the
595
661
  * question (English / German).
596
662
  *
@@ -682,7 +748,7 @@ var TesterPayKitApiClient = class {
682
748
  * Contract: wire.bug_reports.voiceExtractBugFields
683
749
  *
684
750
  * Sends base64-encoded audio to the server. The server runs Whisper
685
- * (transcription) + gpt-4o-mini (structured extraction) and returns
751
+ * (transcription) + gpt-6-luna (structured extraction) and returns
686
752
  * pre-filled bug-report fields in the tester's language.
687
753
  *
688
754
  * Wire body uses snake_case per contract. Timeout is 60 s because
@@ -746,5 +812,8 @@ function assertSessionId(sessionId, op) {
746
812
  }
747
813
  // Annotate the CommonJS export names for ESM import in node:
748
814
  0 && (module.exports = {
749
- TesterPayKitApiClient
815
+ ClientOutdatedError,
816
+ TPK_CLIENT_HEADER,
817
+ TesterPayKitApiClient,
818
+ parseClientOutdated
750
819
  });
package/dist/index.mjs CHANGED
@@ -3,6 +3,22 @@ import axios from "axios";
3
3
  import {
4
4
  TokenManager
5
5
  } from "@testerpaykit/core";
6
+ var TPK_CLIENT_HEADER = "X-TPK-Client";
7
+ var ClientOutdatedError = class extends Error {
8
+ constructor(info) {
9
+ super(info.message ?? "TesterPayKit client is too old for the server.");
10
+ this.info = info;
11
+ this.code = "TPK_CLIENT_OUTDATED";
12
+ this.name = "ClientOutdatedError";
13
+ }
14
+ };
15
+ function parseClientOutdated(status, body) {
16
+ if (status !== 426 || typeof body !== "object" || body === null) return null;
17
+ const b = body;
18
+ if (b.error !== "client_outdated") return null;
19
+ const str = (v) => typeof v === "string" ? v : null;
20
+ return { kind: str(b.kind), min: str(b.min), yours: str(b.yours), message: str(b.message) };
21
+ }
6
22
  var TesterPayKitApiClient = class {
7
23
  constructor(config) {
8
24
  /**
@@ -11,22 +27,43 @@ var TesterPayKitApiClient = class {
11
27
  * tester UI on it. The request still rejects as before.
12
28
  */
13
29
  this.onTesterGate = null;
30
+ /**
31
+ * Called once, on the first 426 `client_outdated` answer. From then on
32
+ * this client sends nothing: every request rejects with
33
+ * [ClientOutdatedError] before it reaches the network.
34
+ */
35
+ this.onClientOutdated = null;
36
+ this.outdated = null;
14
37
  this.apiKey = config.apiKey;
15
38
  this.tokenManager = config.tokenManager || new TokenManager();
39
+ const headers = {
40
+ "Content-Type": "application/json",
41
+ "X-API-Key": this.apiKey
42
+ };
43
+ if (config.clientHeader) headers[TPK_CLIENT_HEADER] = config.clientHeader;
16
44
  this.client = axios.create({
17
45
  baseURL: config.baseURL || "https://api.testerpaykit.com",
18
- headers: {
19
- "Content-Type": "application/json",
20
- "X-API-Key": this.apiKey
21
- }
46
+ headers
22
47
  });
23
48
  this.setupInterceptors();
24
49
  }
50
+ /** Set after a 426 `client_outdated`; null while the server serves us. */
51
+ get clientOutdated() {
52
+ return this.outdated;
53
+ }
54
+ /**
55
+ * Blocks this client as if it had received the 426 itself (an earlier
56
+ * client in the same app run did). Does not call [onClientOutdated].
57
+ */
58
+ markClientOutdated(info) {
59
+ this.outdated ?? (this.outdated = info);
60
+ }
25
61
  /**
26
62
  * Setup request/response interceptors for JWT authentication.
27
63
  */
28
64
  setupInterceptors() {
29
65
  this.client.interceptors.request.use(async (config) => {
66
+ if (this.outdated) throw new ClientOutdatedError(this.outdated);
30
67
  const token = await this.tokenManager.ensureValidToken();
31
68
  if (token) {
32
69
  config.headers.Authorization = `Bearer ${token}`;
@@ -39,6 +76,14 @@ var TesterPayKitApiClient = class {
39
76
  if (error.response?.status === 401) {
40
77
  this.tokenManager.clear();
41
78
  }
79
+ const outdated = parseClientOutdated(error.response?.status, error.response?.data);
80
+ if (outdated && !this.outdated) {
81
+ this.outdated = outdated;
82
+ try {
83
+ this.onClientOutdated?.(outdated);
84
+ } catch {
85
+ }
86
+ }
42
87
  const code = error.response?.data?.error;
43
88
  if (error.response?.status === 403 && (code === "phone_required" || code === "approval_required")) {
44
89
  try {
@@ -444,30 +489,48 @@ var TesterPayKitApiClient = class {
444
489
  return response.data;
445
490
  }
446
491
  /**
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).
492
+ * POST /v1/testers/me/phone/link — a short-lived code for confirming this
493
+ * install in the TPK app (decision 2026-11-10, replaces the SMS dialog).
494
+ * Open `appUrl` (TPK app installed) or `url` (web page with an install
495
+ * hint); the person allows it there, then GET /v1/testers/me/profile
496
+ * reports the install as confirmed.
450
497
  */
451
- async startPhoneVerification(phone) {
498
+ async createAppLink(input) {
452
499
  const response = await this.client.post(
453
- "/v1/testers/me/phone/start",
454
- { phone }
500
+ "/v1/testers/me/phone/link",
501
+ input
455
502
  );
456
503
  return response.data;
457
504
  }
458
505
  /**
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.
506
+ * The test personas of a project and the tester's current choice
507
+ * (GET /v1/testers/me/personas?project_id=). Suggested personas come
508
+ * first; `current` null = "Myself". A 404 (the tester is not in the
509
+ * project yet) yields null: skip the picker silently.
464
510
  */
465
- async confirmPhoneVerification(verificationId, code, device) {
466
- const response = await this.client.post(
467
- "/v1/testers/me/phone/confirm",
468
- { verificationId, code, ...device }
511
+ async getPersonas(projectId) {
512
+ try {
513
+ const response = await this.client.get("/v1/testers/me/personas", {
514
+ params: { project_id: projectId }
515
+ });
516
+ const data = response.data;
517
+ if (!data || !Array.isArray(data.personas)) return null;
518
+ return { current: data.current ?? null, persona: data.persona ?? null, personas: data.personas };
519
+ } catch (e) {
520
+ if (e?.response?.status === 404) return null;
521
+ throw e;
522
+ }
523
+ }
524
+ /**
525
+ * The tester picks a persona (PUT /v1/testers/me/personas);
526
+ * `personaId` null = "Myself". New sessions and reports carry it.
527
+ */
528
+ async setPersona(input) {
529
+ const response = await this.client.put(
530
+ "/v1/testers/me/personas",
531
+ { project_id: input.projectId, persona_id: input.personaId }
469
532
  );
470
- return response.data;
533
+ return { current: response.data?.current ?? null, persona: response.data?.persona ?? null };
471
534
  }
472
535
  async getCompensation() {
473
536
  return (await this.client.get("/v1/testers/me/compensation")).data;
@@ -556,7 +619,7 @@ var TesterPayKitApiClient = class {
556
619
  *
557
620
  * RAG over the project's knowledge-base markdown files. Embeds the
558
621
  * question, retrieves top-K nearest chunks via pgvector cosine
559
- * similarity, and asks gpt-4o-mini to synthesise an answer that
622
+ * similarity, and asks gpt-6-luna to synthesise an answer that
560
623
  * STRICTLY cites those chunks. Answer language tracks the
561
624
  * question (English / German).
562
625
  *
@@ -648,7 +711,7 @@ var TesterPayKitApiClient = class {
648
711
  * Contract: wire.bug_reports.voiceExtractBugFields
649
712
  *
650
713
  * Sends base64-encoded audio to the server. The server runs Whisper
651
- * (transcription) + gpt-4o-mini (structured extraction) and returns
714
+ * (transcription) + gpt-6-luna (structured extraction) and returns
652
715
  * pre-filled bug-report fields in the tester's language.
653
716
  *
654
717
  * Wire body uses snake_case per contract. Timeout is 60 s because
@@ -711,5 +774,8 @@ function assertSessionId(sessionId, op) {
711
774
  }
712
775
  }
713
776
  export {
714
- TesterPayKitApiClient
777
+ ClientOutdatedError,
778
+ TPK_CLIENT_HEADER,
779
+ TesterPayKitApiClient,
780
+ parseClientOutdated
715
781
  };
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@testerpaykit/api-client",
3
- "version": "2.0.0",
3
+ "version": "3.2.0",
4
4
  "description": "API client for TesterPayKit backend",
5
5
  "main": "./dist/index.js",
6
6
  "module": "./dist/index.mjs",
@@ -61,6 +61,51 @@ export interface ApiClientConfig {
61
61
  baseURL?: string;
62
62
  apiKey: string;
63
63
  tokenManager?: TokenManager;
64
+ /**
65
+ * Sent as `X-TPK-Client` on every request, e.g. `expo/2.2.0` (decision
66
+ * 2026-11-14 "Mindestversion je Client-Art"). Default none: the server
67
+ * then serves the request without a version check.
68
+ */
69
+ clientHeader?: string;
70
+ }
71
+
72
+ /** Request header a client identifies itself with (`<kind>/<version>`). */
73
+ export const TPK_CLIENT_HEADER = 'X-TPK-Client';
74
+
75
+ /** Body of a 426 `client_outdated` answer: this client is below the
76
+ * minimum version the server still serves. Fields are null when the
77
+ * request carried no `X-TPK-Client`. */
78
+ export interface ClientOutdatedInfo {
79
+ kind: string | null;
80
+ min: string | null;
81
+ yours: string | null;
82
+ message: string | null;
83
+ }
84
+
85
+ /**
86
+ * Thrown instead of sending, for every request after a 426
87
+ * `client_outdated` (see `TesterPayKitApiClient.clientOutdated`). It has
88
+ * no `response`, so callers that retry on network errors keep their
89
+ * queued work for a newer build instead of dropping it.
90
+ */
91
+ export class ClientOutdatedError extends Error {
92
+ readonly code = 'TPK_CLIENT_OUTDATED';
93
+ constructor(readonly info: ClientOutdatedInfo) {
94
+ super(info.message ?? 'TesterPayKit client is too old for the server.');
95
+ this.name = 'ClientOutdatedError';
96
+ }
97
+ }
98
+
99
+ /** The `client_outdated` body of a 426 answer, else null. */
100
+ export function parseClientOutdated(
101
+ status: number | undefined,
102
+ body: unknown,
103
+ ): ClientOutdatedInfo | null {
104
+ if (status !== 426 || typeof body !== 'object' || body === null) return null;
105
+ const b = body as Record<string, unknown>;
106
+ if (b.error !== 'client_outdated') return null;
107
+ const str = (v: unknown) => (typeof v === 'string' ? v : null);
108
+ return { kind: str(b.kind), min: str(b.min), yours: str(b.yours), message: str(b.message) };
64
109
  }
65
110
 
66
111
  /**
@@ -86,16 +131,40 @@ export class TesterPayKitApiClient implements IApiClient {
86
131
  */
87
132
  onTesterGate: ((reason: TesterGateReason) => void) | null = null;
88
133
 
134
+ /**
135
+ * Called once, on the first 426 `client_outdated` answer. From then on
136
+ * this client sends nothing: every request rejects with
137
+ * [ClientOutdatedError] before it reaches the network.
138
+ */
139
+ onClientOutdated: ((info: ClientOutdatedInfo) => void) | null = null;
140
+
141
+ private outdated: ClientOutdatedInfo | null = null;
142
+
143
+ /** Set after a 426 `client_outdated`; null while the server serves us. */
144
+ get clientOutdated(): ClientOutdatedInfo | null {
145
+ return this.outdated;
146
+ }
147
+
148
+ /**
149
+ * Blocks this client as if it had received the 426 itself (an earlier
150
+ * client in the same app run did). Does not call [onClientOutdated].
151
+ */
152
+ markClientOutdated(info: ClientOutdatedInfo): void {
153
+ this.outdated ??= info;
154
+ }
155
+
89
156
  constructor(config: ApiClientConfig) {
90
157
  this.apiKey = config.apiKey;
91
158
  this.tokenManager = config.tokenManager || new TokenManager();
92
159
 
160
+ const headers: Record<string, string> = {
161
+ 'Content-Type': 'application/json',
162
+ 'X-API-Key': this.apiKey,
163
+ };
164
+ if (config.clientHeader) headers[TPK_CLIENT_HEADER] = config.clientHeader;
93
165
  this.client = axios.create({
94
166
  baseURL: config.baseURL || 'https://api.testerpaykit.com',
95
- headers: {
96
- 'Content-Type': 'application/json',
97
- 'X-API-Key': this.apiKey,
98
- },
167
+ headers,
99
168
  });
100
169
 
101
170
  this.setupInterceptors();
@@ -107,6 +176,8 @@ export class TesterPayKitApiClient implements IApiClient {
107
176
  private setupInterceptors(): void {
108
177
  // Request interceptor: Add auth token to every request
109
178
  this.client.interceptors.request.use(async (config) => {
179
+ // Too old for the server: nothing more goes out in this app run.
180
+ if (this.outdated) throw new ClientOutdatedError(this.outdated);
110
181
  const token = await this.tokenManager.ensureValidToken();
111
182
  if (token) {
112
183
  config.headers.Authorization = `Bearer ${token}`;
@@ -122,6 +193,15 @@ export class TesterPayKitApiClient implements IApiClient {
122
193
  // Token expired or invalid, clear tokens
123
194
  this.tokenManager.clear();
124
195
  }
196
+ const outdated = parseClientOutdated(error.response?.status, error.response?.data);
197
+ if (outdated && !this.outdated) {
198
+ this.outdated = outdated;
199
+ try {
200
+ this.onClientOutdated?.(outdated);
201
+ } catch {
202
+ // A listener problem must not change the request's outcome.
203
+ }
204
+ }
125
205
  const code = error.response?.data?.error;
126
206
  if (
127
207
  error.response?.status === 403 &&
@@ -629,35 +709,56 @@ export class TesterPayKitApiClient implements IApiClient {
629
709
  }
630
710
 
631
711
  /**
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).
712
+ * POST /v1/testers/me/phone/link — a short-lived code for confirming this
713
+ * install in the TPK app (decision 2026-11-10, replaces the SMS dialog).
714
+ * Open `appUrl` (TPK app installed) or `url` (web page with an install
715
+ * hint); the person allows it there, then GET /v1/testers/me/profile
716
+ * reports the install as confirmed.
635
717
  */
636
- async startPhoneVerification(phone: string): Promise<PhoneStartResponse> {
637
- const response = await this.client.post<PhoneStartResponse>(
638
- '/v1/testers/me/phone/start',
639
- { phone },
718
+ async createAppLink(input: {
719
+ projectId?: string;
720
+ platform?: 'ios' | 'android' | 'web';
721
+ }): Promise<AppLinkResponse> {
722
+ const response = await this.client.post<AppLinkResponse>(
723
+ '/v1/testers/me/phone/link',
724
+ input,
640
725
  );
641
726
  return response.data;
642
727
  }
643
728
 
644
729
  /**
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.
730
+ * The test personas of a project and the tester's current choice
731
+ * (GET /v1/testers/me/personas?project_id=). Suggested personas come
732
+ * first; `current` null = "Myself". A 404 (the tester is not in the
733
+ * project yet) yields null: skip the picker silently.
650
734
  */
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 },
735
+ async getPersonas(projectId: string): Promise<TesterPersonaList | null> {
736
+ try {
737
+ const response = await this.client.get<TesterPersonaList>('/v1/testers/me/personas', {
738
+ params: { project_id: projectId },
739
+ });
740
+ const data = response.data;
741
+ if (!data || !Array.isArray(data.personas)) return null;
742
+ return { current: data.current ?? null, persona: data.persona ?? null, personas: data.personas };
743
+ } catch (e) {
744
+ if ((e as { response?: { status?: number } })?.response?.status === 404) return null;
745
+ throw e;
746
+ }
747
+ }
748
+
749
+ /**
750
+ * The tester picks a persona (PUT /v1/testers/me/personas);
751
+ * `personaId` null = "Myself". New sessions and reports carry it.
752
+ */
753
+ async setPersona(input: {
754
+ projectId: string;
755
+ personaId: string | null;
756
+ }): Promise<{ current: string | null; persona: TesterPersona | null }> {
757
+ const response = await this.client.put<{ current: string | null; persona: TesterPersona | null }>(
758
+ '/v1/testers/me/personas',
759
+ { project_id: input.projectId, persona_id: input.personaId },
659
760
  );
660
- return response.data;
761
+ return { current: response.data?.current ?? null, persona: response.data?.persona ?? null };
661
762
  }
662
763
 
663
764
  async getCompensation(): Promise<CompensationWallet> {
@@ -778,7 +879,7 @@ export class TesterPayKitApiClient implements IApiClient {
778
879
  *
779
880
  * RAG over the project's knowledge-base markdown files. Embeds the
780
881
  * question, retrieves top-K nearest chunks via pgvector cosine
781
- * similarity, and asks gpt-4o-mini to synthesise an answer that
882
+ * similarity, and asks gpt-6-luna to synthesise an answer that
782
883
  * STRICTLY cites those chunks. Answer language tracks the
783
884
  * question (English / German).
784
885
  *
@@ -886,7 +987,7 @@ export class TesterPayKitApiClient implements IApiClient {
886
987
  * Contract: wire.bug_reports.voiceExtractBugFields
887
988
  *
888
989
  * Sends base64-encoded audio to the server. The server runs Whisper
889
- * (transcription) + gpt-4o-mini (structured extraction) and returns
990
+ * (transcription) + gpt-6-luna (structured extraction) and returns
890
991
  * pre-filled bug-report fields in the tester's language.
891
992
  *
892
993
  * Wire body uses snake_case per contract. Timeout is 60 s because
@@ -962,7 +1063,7 @@ export interface KnowledgeBaseAnswer {
962
1063
  citations: KnowledgeBaseCitation[];
963
1064
  /** Resolved project UUID — useful for telemetry / dedup. */
964
1065
  projectId: string;
965
- /** Echo of the model used for the answer (e.g. "gpt-4o-mini"). */
1066
+ /** Echo of the model used for the answer (e.g. "gpt-6-luna"). */
966
1067
  model?: string;
967
1068
  }
968
1069
 
@@ -1287,18 +1388,42 @@ export interface TesterProfile {
1287
1388
  createdAt?: string;
1288
1389
  }
1289
1390
 
1290
- export interface PhoneStartResponse {
1291
- verificationId: string;
1292
- expiresInSeconds: number;
1293
- /** Only returned by a development server. */
1294
- devCode?: string;
1391
+ export interface AppLinkResponse {
1392
+ code: string;
1393
+ /** Web page: opens the TPK app via universal link, else an install hint. */
1394
+ url: string;
1395
+ /** testerpaykit://link/<code>, opens the TPK app directly. */
1396
+ appUrl: string;
1397
+ expiresAt: string;
1398
+ }
1399
+
1400
+ /** A text in both UI languages. */
1401
+ export interface TesterPersonaText {
1402
+ de: string;
1403
+ en: string;
1404
+ }
1405
+
1406
+ /** One test persona (made-up data; never real data of the tester). */
1407
+ export interface TesterPersona {
1408
+ id: string;
1409
+ /** True for a persona the developer made for this project. */
1410
+ own: boolean;
1411
+ slug?: string | null;
1412
+ title: TesterPersonaText;
1413
+ sub: TesterPersonaText;
1414
+ briefing: TesterPersonaText;
1415
+ watch: { de: string[]; en: string[] };
1416
+ attributes: Record<string, unknown>;
1417
+ /** The developer suggested it (those come first). */
1418
+ suggested?: boolean;
1295
1419
  }
1296
1420
 
1297
- export interface PhoneConfirmResponse {
1298
- handle: string;
1299
- phoneVerified: boolean;
1300
- /** Tester status after the confirmation (e.g. `active`, `pending`). */
1301
- status?: string | null;
1421
+ /** Answer of GET /v1/testers/me/personas. */
1422
+ export interface TesterPersonaList {
1423
+ /** The chosen persona id; null = "Myself". */
1424
+ current: string | null;
1425
+ persona: TesterPersona | null;
1426
+ personas: TesterPersona[];
1302
1427
  }
1303
1428
 
1304
1429
  export interface TesterPoints {
@@ -1,6 +1,9 @@
1
1
  import { describe, it, expect, vi, beforeEach } from 'vitest';
2
2
  import axios from 'axios';
3
- import { TesterPayKitApiClient } from '../src/TesterPayKitApiClient';
3
+ import {
4
+ ClientOutdatedError,
5
+ TesterPayKitApiClient,
6
+ } from '../src/TesterPayKitApiClient';
4
7
  import { TokenManager } from '@testerpaykit/core';
5
8
 
6
9
  // Mock axios
@@ -19,6 +22,7 @@ describe('TesterPayKitApiClient', () => {
19
22
  // Create mock axios instance
20
23
  mockAxiosInstance = {
21
24
  post: vi.fn(),
25
+ put: vi.fn(),
22
26
  get: vi.fn(),
23
27
  interceptors: {
24
28
  request: {
@@ -95,6 +99,61 @@ describe('TesterPayKitApiClient', () => {
95
99
  });
96
100
  });
97
101
 
102
+ describe('client version check', () => {
103
+ const outdatedBody = {
104
+ error: 'client_outdated',
105
+ kind: 'expo',
106
+ min: '2.2.0',
107
+ yours: '2.1.0',
108
+ message: 'too old',
109
+ };
110
+
111
+ it('sends no X-TPK-Client unless the caller sets one', () => {
112
+ new TesterPayKitApiClient({ apiKey: 'k', clientHeader: 'expo/2.2.0' });
113
+ expect(mockedAxios.create).toHaveBeenLastCalledWith({
114
+ baseURL: 'https://api.testerpaykit.com',
115
+ headers: {
116
+ 'Content-Type': 'application/json',
117
+ 'X-API-Key': 'k',
118
+ 'X-TPK-Client': 'expo/2.2.0',
119
+ },
120
+ });
121
+ });
122
+
123
+ it('426 client_outdated: reports once, then sends nothing more', async () => {
124
+ const onRequest = mockAxiosInstance.interceptors.request.use.mock.calls[0][0];
125
+ const onError = mockAxiosInstance.interceptors.response.use.mock.calls[0][1];
126
+ const seen: unknown[] = [];
127
+ client.onClientOutdated = (info) => seen.push(info);
128
+
129
+ expect(client.clientOutdated).toBeNull();
130
+ await expect(onRequest({ headers: {} })).resolves.toBeTruthy();
131
+
132
+ await expect(
133
+ onError({ response: { status: 426, data: outdatedBody } }),
134
+ ).rejects.toBeTruthy();
135
+ await expect(
136
+ onError({ response: { status: 426, data: outdatedBody } }),
137
+ ).rejects.toBeTruthy();
138
+
139
+ const info = { kind: 'expo', min: '2.2.0', yours: '2.1.0', message: 'too old' };
140
+ expect(seen).toEqual([info]);
141
+ expect(client.clientOutdated).toEqual(info);
142
+ const blocked = onRequest({ headers: {} });
143
+ await expect(blocked).rejects.toBeInstanceOf(ClientOutdatedError);
144
+ await expect(blocked).rejects.toMatchObject({ info });
145
+ await expect(blocked).rejects.not.toHaveProperty('response');
146
+ });
147
+
148
+ it('ignores a 426 without client_outdated', async () => {
149
+ const onError = mockAxiosInstance.interceptors.response.use.mock.calls[0][1];
150
+ await expect(
151
+ onError({ response: { status: 426, data: { error: 'other' } } }),
152
+ ).rejects.toBeTruthy();
153
+ expect(client.clientOutdated).toBeNull();
154
+ });
155
+ });
156
+
98
157
  describe('login', () => {
99
158
  it('should successfully login and store tokens', async () => {
100
159
  const loginRequest = {
@@ -245,6 +304,44 @@ describe('TesterPayKitApiClient', () => {
245
304
  });
246
305
  });
247
306
 
307
+ describe('personas', () => {
308
+ const list = { current: null, persona: null, personas: [{ id: 'a', own: false, title: { de: 'A', en: 'A' } }] };
309
+
310
+ it('reads the personas of a project', async () => {
311
+ mockAxiosInstance.get.mockResolvedValue({ data: list });
312
+ await expect(client.getPersonas('p-1')).resolves.toEqual(list);
313
+ expect(mockAxiosInstance.get).toHaveBeenCalledWith('/v1/testers/me/personas', { params: { project_id: 'p-1' } });
314
+ });
315
+
316
+ it('treats 404 (not in the project yet) as no personas', async () => {
317
+ mockAxiosInstance.get.mockRejectedValue({ response: { status: 404 } });
318
+ await expect(client.getPersonas('p-1')).resolves.toBeNull();
319
+ });
320
+
321
+ it('rethrows other errors', async () => {
322
+ mockAxiosInstance.get.mockRejectedValue({ response: { status: 500 } });
323
+ await expect(client.getPersonas('p-1')).rejects.toEqual({ response: { status: 500 } });
324
+ });
325
+
326
+ it('chooses a persona, and "Myself" as null', async () => {
327
+ mockAxiosInstance.put.mockResolvedValue({ data: { current: 'a', persona: list.personas[0] } });
328
+ await expect(client.setPersona({ projectId: 'p-1', personaId: 'a' })).resolves.toEqual({
329
+ current: 'a',
330
+ persona: list.personas[0],
331
+ });
332
+ expect(mockAxiosInstance.put).toHaveBeenCalledWith('/v1/testers/me/personas', {
333
+ project_id: 'p-1',
334
+ persona_id: 'a',
335
+ });
336
+ mockAxiosInstance.put.mockResolvedValue({ data: { current: null, persona: null } });
337
+ await client.setPersona({ projectId: 'p-1', personaId: null });
338
+ expect(mockAxiosInstance.put).toHaveBeenLastCalledWith('/v1/testers/me/personas', {
339
+ project_id: 'p-1',
340
+ persona_id: null,
341
+ });
342
+ });
343
+ });
344
+
248
345
  describe('checklist', () => {
249
346
  it('reads the checklist of a project', async () => {
250
347
  const tasks = [{ id: 't1', title: 'Login', steps: ['Open', 'Sign in'], mine: { status: 'passed', steps: [], at: 'x' } }];