@mundogamernetwork/shared-ui 1.1.96 → 1.2.1

package/services/playtestTesterService.ts

@@ -0,0 +1,416 @@
+import httpService from './httpService'
+
+// Playtest tester-facing service — every endpoint under /playtest/* consumed
+// by the tester-facing response-taking flows (baseline, concept polls,
+// localization QA, accessibility audits, compliance checklists, moderated
+// sessions). Mirrors keyService.ts's flat function-export style: thin
+// wrappers over httpService (cookie-auth axios instance, no manual token
+// plumbing — see services/httpService.ts).
+//
+// All routes verified directly against api-main's PlaytestProvider route
+// registration and Request/Controller classes this session (not assumed from
+// the plan doc) — see docs/playtest/00-feature-map.md in api-main.
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export type PlaytestEngine = 'quick' | 'deep'
+
+export interface PlaytestFormSectionMeta {
+  label: string
+  engines: PlaytestEngine[]
+  scale: boolean
+  text: 'none' | 'optional' | 'required'
+  default: boolean
+}
+
+export interface PlaytestCatalog {
+  engines: PlaytestEngine[]
+  sections: Record<string, PlaytestFormSectionMeta>
+}
+
+export interface PlaytestCampaign {
+  id: number
+  user_id: number
+  title: string
+  game_ref: string | null
+  engine: PlaytestEngine
+  category: 'concept_poll' | 'localization_qa' | 'accessibility_audit' | null
+  status: string
+  enabled_sections: string[]
+  audience: Record<string, any> | null
+  accessibility_criteria: string[] | null
+  targeting_level: 'open' | 'matched_only' | 'basic' | string
+  responses_requested: number
+  responses_accepted: number
+  reward_type: 'mgc' | 'cash'
+  reward_amount: string | number
+  reward_currency: string | null
+  closes_at: string | null
+  eligible?: boolean
+  ineligibility_reason?: string | null
+  [key: string]: any
+}
+
+export interface PlaytestAnswerEntry {
+  rating?: number
+  text?: string
+}
+
+export interface SubmitBaselineResponsePayload {
+  answers: Record<string, PlaytestAnswerEntry>
+  time_on_task_seconds?: number
+  device?: string
+  os?: string
+}
+
+export interface PlaytestResponse {
+  id: number
+  playtest_campaign_id: number
+  user_id: number
+  status: 'submitted' | 'accepted' | 'rejected'
+  answers: Record<string, PlaytestAnswerEntry> | null
+  quality_score: number | null
+  time_on_task_seconds: number | null
+  device: string | null
+  os: string | null
+  reward_status: string | null
+  target_locale: string | null
+  campaign?: PlaytestCampaign
+  payout?: any
+  [key: string]: any
+}
+
+export type ConceptPollType =
+  | 'head_to_head'
+  | 'single_select'
+  | 'multi_select'
+  | 'ranked_choice'
+  | 'five_second_test'
+  | 'star_rating'
+  | 'emoji_reaction'
+
+export interface PlaytestConceptPollOption {
+  id: number
+  playtest_concept_poll_id: number
+  label: string
+  value: string | null
+  media_url: string | null
+  position: number
+  votes: number
+}
+
+export interface PlaytestConceptPoll {
+  id: number
+  playtest_campaign_id: number
+  poll_type: ConceptPollType
+  asset_kind: string | null
+  question: string
+  description: string | null
+  status: string
+  closes_at: string | null
+  options: PlaytestConceptPollOption[]
+  campaign?: PlaytestCampaign
+}
+
+// `answer` shape strictly depends on poll_type — see VoteConceptPollRequest.php,
+// verified this session. `reason` is UNCONDITIONALLY required regardless of
+// poll_type (min 3 chars) — a PickFu-style convention, not optional anywhere.
+export type ConceptPollAnswer =
+  | { option_id: number } // head_to_head | single_select
+  | { option_id: number; recall_text: string } // five_second_test
+  | { option_id: number; stars: number } // star_rating (1-5)
+  | { option_id: number; emoji: string } // emoji_reaction
+  | { option_ids: number[] } // multi_select
+  | { ranking: number[] } // ranked_choice
+
+export interface VoteConceptPollPayload {
+  answer: ConceptPollAnswer
+  reason: string
+}
+
+export interface PlaytestCampaignLocale {
+  id: number
+  playtest_campaign_id: number
+  locale: string
+  build_reference: string | null
+  responses_target: number
+  responses_received: number
+}
+
+export type LocalizationIssueType =
+  | 'mistranslation'
+  | 'text_truncation'
+  | 'missing_string'
+  | 'cultural_inappropriateness'
+  | 'audio_subtitle_desync'
+  | 'untranslated_string'
+  | 'grammar_punctuation'
+  | 'inconsistent_terminology'
+
+export type LocalizationIssueSeverity = 'blocker' | 'critical' | 'major' | 'minor' | 'cosmetic'
+
+export interface StoreLocalizationIssuePayload {
+  campaign_locale_id: number
+  issue_type: LocalizationIssueType
+  severity: LocalizationIssueSeverity
+  location?: string | null
+  description: string
+  expected_text?: string | null
+  actual_text?: string | null
+  media_url?: string | null
+}
+
+export interface PlaytestLocalizationIssue extends StoreLocalizationIssuePayload {
+  id: number
+  playtest_campaign_id: number
+  playtest_response_id: number
+  user_id: number
+  status: string
+  created_at: string
+}
+
+export interface PlaytestAccessibilityCriterionMeta {
+  label: string
+  accommodation: string
+}
+
+export type AccessibilityCriteriaCatalog = Record<string, PlaytestAccessibilityCriterionMeta>
+
+export type AccessibilityEvaluationResult = 'pass' | 'fail' | 'partial' | 'not_applicable'
+
+export interface AccessibilityEvaluationEntry {
+  criterion: string
+  result: AccessibilityEvaluationResult
+  notes?: string | null
+  tester_uses_accommodation?: boolean
+}
+
+export interface SubmitAccessibilityEvaluationsPayload {
+  evaluations: AccessibilityEvaluationEntry[]
+}
+
+export interface PlaytestComplianceChecklistItem {
+  key: string
+  label: string
+  description?: string | null
+  severity?: string | null
+  evidence_required?: boolean
+}
+
+export interface PlaytestComplianceChecklist {
+  id: number
+  playtest_campaign_id: number
+  name: string
+  category: string
+  items: PlaytestComplianceChecklistItem[]
+  campaign?: PlaytestCampaign
+}
+
+export type ComplianceResultStatus = 'pass' | 'fail' | 'not_applicable'
+
+export interface ComplianceResultEntry {
+  key: string
+  status: ComplianceResultStatus
+  notes?: string | null
+  evidence_url?: string | null
+}
+
+// This endpoint FULLY REPLACES the whole `results` array server-side on every
+// call (SubmitComplianceResultRequest + PlaytestComplianceRepository::submitResult
+// upsert the checklist's full result set) — callers must always send the
+// complete accumulated array, never a diff, or previously-completed items are
+// silently dropped. Enforced client-side by usePlaytestResponse's accumulator.
+export interface SubmitComplianceResultPayload {
+  results: ComplianceResultEntry[]
+}
+
+export interface PlaytestModeratedSlot {
+  id: number
+  playtest_campaign_id: number
+  moderator_id: number
+  moderator_type: 'studio' | 'mgn_staff'
+  starts_at: string
+  duration_minutes: number
+  is_booked: boolean
+  notes: string | null
+}
+
+export type PlaytestModeratedSessionStatus = 'scheduled' | 'completed' | 'no_show' | 'cancelled'
+
+export interface PlaytestModeratedSession {
+  id: number
+  playtest_campaign_id: number
+  playtest_moderated_slot_id: number
+  tester_id: number
+  moderator_id: number
+  moderator_type: 'studio' | 'mgn_staff'
+  meeting_id: number | null
+  scheduled_at: string
+  duration_minutes: number
+  status: PlaytestModeratedSessionStatus
+  playtest_response_id: number | null
+  moderator_summary: string | null
+  recording_url: string | null
+  completed_at: string | null
+  cancelled_at: string | null
+  cancellation_reason: string | null
+  tester_confirmed_at: string | null
+  campaign?: PlaytestCampaign
+  slot?: PlaytestModeratedSlot
+  // Eager-loaded by PlaytestModeratedSessionRepository::findWithRelations()
+  // (used by GET /playtest/moderated-sessions/{id}) — meeting_link is the
+  // actual join-call URL (Meeting model, app/Models/Meeting.php).
+  meeting?: { id: number; meeting_link: string | null; meeting_provider_id: string | null; platform: string | null } | null
+  [key: string]: any
+}
+
+export interface UploadPlaytestMediaResult {
+  data: { url: string }
+}
+
+export interface PaginatedResponse<T> {
+  data: T[]
+  meta?: { pagination?: Record<string, any> }
+  current_page?: number
+  last_page?: number
+  total?: number
+  [key: string]: any
+}
+
+// ---------------------------------------------------------------------------
+// Catalog / discovery
+// ---------------------------------------------------------------------------
+
+/** Public: engines + modular baseline section catalog. */
+export const fetchPlaytestCatalog = () =>
+  httpService.get<PlaytestCatalog>('/playtest/catalog')
+
+/** Authenticated: active campaigns open to the tester, with eligibility. */
+export const fetchAvailablePlaytestCampaigns = () =>
+  httpService.get<PlaytestCampaign[]>('/playtest/available')
+
+// ---------------------------------------------------------------------------
+// Baseline (quick/deep, category=null)
+// ---------------------------------------------------------------------------
+
+/**
+ * Submit (or, on repeat call, no-op — firstOrCreate is idempotent server-side)
+ * a baseline response. Creates the underlying PlaytestResponse lazily.
+ */
+export const submitPlaytestResponse = (campaignId: number, payload: SubmitBaselineResponsePayload) =>
+  httpService.post<PlaytestResponse>(`/playtest/campaigns/${campaignId}/responses`, payload)
+
+// ---------------------------------------------------------------------------
+// Concept polls (category=concept_poll, engine=quick)
+// ---------------------------------------------------------------------------
+
+export const fetchConceptPoll = (pollId: number) =>
+  httpService.get<PlaytestConceptPoll>(`/playtest/concept-polls/${pollId}`)
+
+/** reason is unconditionally required (min 3 chars) for every poll_type. */
+export const voteConceptPoll = (pollId: number, payload: VoteConceptPollPayload) =>
+  httpService.post(`/playtest/concept-polls/${pollId}/vote`, payload)
+
+// ---------------------------------------------------------------------------
+// Localization QA (category=localization_qa)
+// ---------------------------------------------------------------------------
+
+export const fetchCampaignLocales = (campaignId: number) =>
+  httpService.get<PlaytestCampaignLocale[]>(`/playtest/campaigns/${campaignId}/locales`)
+
+/**
+ * Files a localization defect. The first issue filed on a campaign lazily
+ * creates the tester's PlaytestResponse server-side — no separate "start"
+ * call exists or is needed.
+ */
+export const storeLocalizationIssue = (campaignId: number, payload: StoreLocalizationIssuePayload) =>
+  httpService.post<PlaytestLocalizationIssue>(`/playtest/campaigns/${campaignId}/localization-issues`, payload)
+
+// ---------------------------------------------------------------------------
+// Accessibility audits (category=accessibility_audit)
+// ---------------------------------------------------------------------------
+
+/** Public: fixed catalog of 7 accessibility criteria. */
+export const fetchAccessibilityCriteriaCatalog = () =>
+  httpService.get<AccessibilityCriteriaCatalog>('/playtest/accessibility-criteria')
+
+/**
+ * Batch-submits criterion evaluations. Server-side this upserts per-criterion
+ * (safe to auto-save each criterion as completed as the tester progresses,
+ * not just at the end) — unlike compliance results below, this is NOT a
+ * full-replace endpoint.
+ */
+export const submitAccessibilityEvaluations = (campaignId: number, payload: SubmitAccessibilityEvaluationsPayload) =>
+  httpService.post(`/playtest/campaigns/${campaignId}/accessibility-evaluations`, payload)
+
+// ---------------------------------------------------------------------------
+// Compliance / technical QA checklists (capability layered on any campaign)
+// ---------------------------------------------------------------------------
+
+export const fetchComplianceChecklists = (campaignId: number) =>
+  httpService.get<PlaytestComplianceChecklist[]>(`/playtest/campaigns/${campaignId}/compliance-checklists`)
+
+/**
+ * Submits results for one checklist. IMPORTANT: this fully REPLACES the whole
+ * `results` array server-side on every call — always send the complete
+ * accumulated array (every item answered so far), never a diff, or
+ * previously-completed items are silently dropped.
+ */
+export const submitComplianceResult = (checklistId: number, payload: SubmitComplianceResultPayload) =>
+  httpService.post(`/playtest/compliance-checklists/${checklistId}/results`, payload)
+
+// ---------------------------------------------------------------------------
+// Moderated / live sessions
+// ---------------------------------------------------------------------------
+
+export const fetchAvailableModeratedSlots = (campaignId: number) =>
+  httpService.get<PlaytestModeratedSlot[]>(`/playtest/campaigns/${campaignId}/moderated-slots/available`)
+
+export const claimModeratedSlot = (slotId: number) =>
+  httpService.post<PlaytestModeratedSession>(`/playtest/moderated-slots/${slotId}/claim`)
+
+export const fetchMyModeratedSessions = () =>
+  httpService.get<PlaytestModeratedSession[]>('/playtest/my-moderated-sessions')
+
+export const fetchModeratedSession = (sessionId: number) =>
+  httpService.get<PlaytestModeratedSession>(`/playtest/moderated-sessions/${sessionId}`)
+
+/** Additive tester signal (sets tester_confirmed_at) — does not change `status`. */
+export const confirmModeratedSession = (sessionId: number) =>
+  httpService.post<PlaytestModeratedSession>(`/playtest/moderated-sessions/${sessionId}/confirm`)
+
+export const markModeratedSessionNoShow = (sessionId: number) =>
+  httpService.post<PlaytestModeratedSession>(`/playtest/moderated-sessions/${sessionId}/no-show`)
+
+export const cancelModeratedSession = (sessionId: number, cancellationReason?: string) =>
+  httpService.post<PlaytestModeratedSession>(`/playtest/moderated-sessions/${sessionId}/cancel`, {
+    cancellation_reason: cancellationReason ?? null,
+  })
+
+// ---------------------------------------------------------------------------
+// Media upload (LQA media_url / compliance evidence_url)
+// ---------------------------------------------------------------------------
+
+/**
+ * Generic tester media upload — jpg/jpeg/gif/png/webp/mp4/mov/webm up to
+ * 20MB. Returns {data:{url}}. Use the resulting url as LQA's media_url or
+ * compliance's evidence_url.
+ */
+export const uploadPlaytestMedia = (file: File) => {
+  const form = new FormData()
+  form.append('file', file)
+  return httpService.post<UploadPlaytestMediaResult>('/playtest/media', form, {
+    headers: { 'Content-Type': 'multipart/form-data' },
+  })
+}
+
+// ---------------------------------------------------------------------------
+// My responses (tester-scoped; consuming app builds the actual list UI)
+// ---------------------------------------------------------------------------
+
+export const fetchMyPlaytestResponses = (status?: 'submitted' | 'accepted' | 'rejected', perPage = 20, page = 1) =>
+  httpService.get<PaginatedResponse<PlaytestResponse>>('/playtest/my-responses', {
+    params: { status, per_page: perPage, page },
+  })