@mundogamernetwork/shared-ui 1.1.96 → 1.2.0

package/composables/usePlaytestResponse.ts

@@ -0,0 +1,446 @@
+import { ref, reactive, computed } from "vue";
+import {
+	fetchPlaytestCatalog,
+	fetchAvailablePlaytestCampaigns,
+	submitPlaytestResponse,
+	fetchConceptPoll,
+	voteConceptPoll,
+	fetchCampaignLocales,
+	storeLocalizationIssue,
+	fetchAccessibilityCriteriaCatalog,
+	submitAccessibilityEvaluations,
+	fetchComplianceChecklists,
+	submitComplianceResult,
+	fetchAvailableModeratedSlots,
+	claimModeratedSlot,
+	fetchMyModeratedSessions,
+	fetchModeratedSession,
+	confirmModeratedSession,
+	markModeratedSessionNoShow,
+	cancelModeratedSession,
+	uploadPlaytestMedia,
+	fetchMyPlaytestResponses,
+	type PlaytestCampaign,
+	type PlaytestCatalog,
+	type PlaytestAnswerEntry,
+	type SubmitBaselineResponsePayload,
+	type PlaytestConceptPoll,
+	type ConceptPollAnswer,
+	type PlaytestCampaignLocale,
+	type StoreLocalizationIssuePayload,
+	type PlaytestLocalizationIssue,
+	type AccessibilityCriteriaCatalog,
+	type AccessibilityEvaluationEntry,
+	type PlaytestComplianceChecklist,
+	type ComplianceResultEntry,
+	type PlaytestModeratedSlot,
+	type PlaytestModeratedSession,
+} from "../services/playtestTesterService";
+
+/**
+ * Accumulates client-side answer/vote/issue/evaluation/result state for a
+ * single campaign visit, and centralizes the "you no longer qualify" (422)
+ * handling every submit endpoint can independently throw — every submit path
+ * re-checks PlaytestService::assertEligible() server-side, even when a prior
+ * screen already confirmed eligibility (a campaign's audience rules, or the
+ * tester's own certifications, can change between page-load and submit).
+ *
+ * One instance per campaign visit — instantiate fresh per mount
+ * (PlaytestResponseFlow.vue owns the instance), not as a global singleton.
+ */
+export function usePlaytestResponse(campaignId: number) {
+	// ── Shared/global state ────────────────────────────────────────────────
+	const loading = ref(false);
+	const submitting = ref(false);
+
+	// Structured ineligibility state — distinct from generic errors so the UI
+	// can render a dedicated "you no longer qualify" panel instead of a toast.
+	const ineligible = ref(false);
+	const ineligibilityReason = ref<string | null>(null);
+	const genericError = ref<string | null>(null);
+
+	function resetErrors() {
+		ineligible.value = false;
+		ineligibilityReason.value = null;
+		genericError.value = null;
+	}
+
+	/**
+	 * Every submit endpoint returns a 422 (via each controller's guarded()
+	 * wrapper around PlaytestService::assertEligible()) when the tester no
+	 * longer qualifies — must be handled gracefully on every call site, not
+	 * just assumed-passed because a previous screen displayed `eligible: true`.
+	 */
+	function handleError(e: any): never {
+		const status = e?.response?.status;
+		const message: string = e?.response?.data?.message ?? "";
+
+		if (status === 422) {
+			ineligible.value = true;
+			ineligibilityReason.value = message || null;
+		} else {
+			genericError.value = message || e?.message || "Something went wrong. Please try again.";
+		}
+
+		throw e;
+	}
+
+	async function withGuard<T>(fn: () => Promise<T>): Promise<T | null> {
+		resetErrors();
+		submitting.value = true;
+		try {
+			return await fn();
+		} catch (e) {
+			try {
+				handleError(e);
+			} catch {
+				return null;
+			}
+			return null;
+		} finally {
+			submitting.value = false;
+		}
+	}
+
+	// ── Catalog (baseline sections) ────────────────────────────────────────
+	const catalog = ref<PlaytestCatalog | null>(null);
+
+	async function loadCatalog() {
+		loading.value = true;
+		try {
+			const res = await fetchPlaytestCatalog();
+			catalog.value = res.data;
+		} finally {
+			loading.value = false;
+		}
+	}
+
+	// ── Campaign (available() list entry, carries eligibility) ────────────
+	const campaign = ref<PlaytestCampaign | null>(null);
+
+	async function loadCampaignEligibility() {
+		loading.value = true;
+		try {
+			const res = await fetchAvailablePlaytestCampaigns();
+			const found = res.data.find((c) => c.id === campaignId) ?? null;
+			campaign.value = found;
+			if (found && found.eligible === false) {
+				ineligible.value = true;
+				ineligibilityReason.value = found.ineligibility_reason ?? null;
+			}
+			return found;
+		} finally {
+			loading.value = false;
+		}
+	}
+
+	// ── Baseline answers accumulator ───────────────────────────────────────
+	const baselineAnswers = reactive<Record<string, PlaytestAnswerEntry>>({});
+
+	function setBaselineAnswer(sectionKey: string, entry: PlaytestAnswerEntry) {
+		baselineAnswers[sectionKey] = { ...baselineAnswers[sectionKey], ...entry };
+	}
+
+	async function submitBaseline(meta: Omit<SubmitBaselineResponsePayload, "answers"> = {}) {
+		return withGuard(async () => {
+			const res = await submitPlaytestResponse(campaignId, {
+				answers: { ...baselineAnswers },
+				...meta,
+			});
+			return res.data;
+		});
+	}
+
+	// ── Concept poll ────────────────────────────────────────────────────────
+	const poll = ref<PlaytestConceptPoll | null>(null);
+
+	async function loadConceptPoll(pollId: number) {
+		loading.value = true;
+		try {
+			const res = await fetchConceptPoll(pollId);
+			poll.value = res.data;
+		} finally {
+			loading.value = false;
+		}
+	}
+
+	async function submitConceptPollVote(pollId: number, answer: ConceptPollAnswer, reason: string) {
+		return withGuard(async () => {
+			const res = await voteConceptPoll(pollId, { answer, reason });
+			return res.data;
+		});
+	}
+
+	// ── Localization QA ────────────────────────────────────────────────────
+	const locales = ref<PlaytestCampaignLocale[]>([]);
+	const filedIssues = ref<PlaytestLocalizationIssue[]>([]);
+
+	async function loadCampaignLocales() {
+		loading.value = true;
+		try {
+			const res = await fetchCampaignLocales(campaignId);
+			locales.value = res.data;
+		} finally {
+			loading.value = false;
+		}
+	}
+
+	async function fileLocalizationIssue(payload: StoreLocalizationIssuePayload) {
+		return withGuard(async () => {
+			const res = await storeLocalizationIssue(campaignId, payload);
+			filedIssues.value.push(res.data);
+			return res.data;
+		});
+	}
+
+	// ── Accessibility ───────────────────────────────────────────────────────
+	const accessibilityCriteria = ref<AccessibilityCriteriaCatalog>({});
+	// criterion key -> completed evaluation entry, so the UI can auto-save
+	// each criterion independently (server upserts per-criterion — safe).
+	const accessibilityEvaluations = reactive<Record<string, AccessibilityEvaluationEntry>>({});
+
+	async function loadAccessibilityCriteria() {
+		loading.value = true;
+		try {
+			const res = await fetchAccessibilityCriteriaCatalog();
+			accessibilityCriteria.value = res.data;
+		} finally {
+			loading.value = false;
+		}
+	}
+
+	function setAccessibilityEvaluation(entry: AccessibilityEvaluationEntry) {
+		accessibilityEvaluations[entry.criterion] = entry;
+	}
+
+	/**
+	 * Submits one (or more) criterion evaluations. Safe to call per-criterion
+	 * as the tester completes each one (upsert semantics server-side) — pass
+	 * just the newly-completed entry, or omit `entries` to flush everything
+	 * accumulated so far.
+	 */
+	async function submitAccessibilityBatch(entries?: AccessibilityEvaluationEntry[]) {
+		return withGuard(async () => {
+			const payload = entries ?? Object.values(accessibilityEvaluations);
+			const res = await submitAccessibilityEvaluations(campaignId, { evaluations: payload });
+			return res.data;
+		});
+	}
+
+	// ── Compliance checklists ──────────────────────────────────────────────
+	const complianceChecklists = ref<PlaytestComplianceChecklist[]>([]);
+	// checklistId -> (key -> result entry). Kept per-checklist because the
+	// submit endpoint fully REPLACES the whole `results` array per checklist —
+	// callers must always send the complete accumulated set for that
+	// checklist, never a diff.
+	const complianceResults = reactive<Record<number, Record<string, ComplianceResultEntry>>>({});
+
+	async function loadComplianceChecklists() {
+		loading.value = true;
+		try {
+			const res = await fetchComplianceChecklists(campaignId);
+			complianceChecklists.value = res.data;
+			res.data.forEach((c) => {
+				if (!complianceResults[c.id]) complianceResults[c.id] = {};
+			});
+		} finally {
+			loading.value = false;
+		}
+	}
+
+	function setComplianceResult(checklistId: number, entry: ComplianceResultEntry) {
+		if (!complianceResults[checklistId]) complianceResults[checklistId] = {};
+		complianceResults[checklistId][entry.key] = entry;
+	}
+
+	/**
+	 * Always sends the FULL accumulated results array for this checklist —
+	 * never a diff — since the backend replaces the whole array on every call.
+	 */
+	async function submitComplianceChecklist(checklistId: number) {
+		return withGuard(async () => {
+			const results = Object.values(complianceResults[checklistId] ?? {});
+			const res = await submitComplianceResult(checklistId, { results });
+			return res.data;
+		});
+	}
+
+	// ── Moderated sessions ──────────────────────────────────────────────────
+	const moderatedSlots = ref<PlaytestModeratedSlot[]>([]);
+	const mySessions = ref<PlaytestModeratedSession[]>([]);
+	const currentSession = ref<PlaytestModeratedSession | null>(null);
+
+	async function loadAvailableModeratedSlots() {
+		loading.value = true;
+		try {
+			const res = await fetchAvailableModeratedSlots(campaignId);
+			// availableSlots() has no server-side eligibility pre-filtering
+			// (documented gap) — the client is expected to work around it by
+			// still attempting the claim, which re-checks eligibility server-
+			// side and surfaces a 422 gracefully via withGuard() if it fails.
+			moderatedSlots.value = res.data;
+		} finally {
+			loading.value = false;
+		}
+	}
+
+	async function claimSlot(slotId: number) {
+		return withGuard(async () => {
+			const res = await claimModeratedSlot(slotId);
+			currentSession.value = res.data;
+			return res.data;
+		});
+	}
+
+	async function loadMySessions() {
+		loading.value = true;
+		try {
+			const res = await fetchMyModeratedSessions();
+			mySessions.value = res.data;
+		} finally {
+			loading.value = false;
+		}
+	}
+
+	async function loadSession(sessionId: number) {
+		loading.value = true;
+		try {
+			const res = await fetchModeratedSession(sessionId);
+			currentSession.value = res.data;
+			return res.data;
+		} finally {
+			loading.value = false;
+		}
+	}
+
+	async function confirmSession(sessionId: number) {
+		return withGuard(async () => {
+			const res = await confirmModeratedSession(sessionId);
+			currentSession.value = res.data;
+			return res.data;
+		});
+	}
+
+	async function noShowSession(sessionId: number) {
+		return withGuard(async () => {
+			const res = await markModeratedSessionNoShow(sessionId);
+			currentSession.value = res.data;
+			return res.data;
+		});
+	}
+
+	async function cancelSession(sessionId: number, reason?: string) {
+		return withGuard(async () => {
+			const res = await cancelModeratedSession(sessionId, reason);
+			currentSession.value = res.data;
+			return res.data;
+		});
+	}
+
+	// ── Media upload ────────────────────────────────────────────────────────
+	const uploading = ref(false);
+
+	async function uploadMedia(file: File): Promise<string | null> {
+		uploading.value = true;
+		try {
+			const res = await uploadPlaytestMedia(file);
+			return res.data?.data?.url ?? null;
+		} catch (e) {
+			try {
+				handleError(e);
+			} catch {
+				return null;
+			}
+			return null;
+		} finally {
+			uploading.value = false;
+		}
+	}
+
+	// ── My responses (fetch exposed for consuming-app dashboards) ─────────
+	const myResponses = ref<any[]>([]);
+
+	async function loadMyResponses(status?: "submitted" | "accepted" | "rejected") {
+		loading.value = true;
+		try {
+			const res = await fetchMyPlaytestResponses(status);
+			myResponses.value = res.data?.data ?? [];
+			return res.data;
+		} finally {
+			loading.value = false;
+		}
+	}
+
+	const hasError = computed(() => ineligible.value || !!genericError.value);
+
+	return {
+		// state
+		loading,
+		submitting,
+		uploading,
+		ineligible,
+		ineligibilityReason,
+		genericError,
+		hasError,
+
+		// catalog / discovery
+		catalog,
+		campaign,
+		loadCatalog,
+		loadCampaignEligibility,
+
+		// baseline
+		baselineAnswers,
+		setBaselineAnswer,
+		submitBaseline,
+
+		// concept poll
+		poll,
+		loadConceptPoll,
+		submitConceptPollVote,
+
+		// localization QA
+		locales,
+		filedIssues,
+		loadCampaignLocales,
+		fileLocalizationIssue,
+
+		// accessibility
+		accessibilityCriteria,
+		accessibilityEvaluations,
+		loadAccessibilityCriteria,
+		setAccessibilityEvaluation,
+		submitAccessibilityBatch,
+
+		// compliance
+		complianceChecklists,
+		complianceResults,
+		loadComplianceChecklists,
+		setComplianceResult,
+		submitComplianceChecklist,
+
+		// moderated sessions
+		moderatedSlots,
+		mySessions,
+		currentSession,
+		loadAvailableModeratedSlots,
+		claimSlot,
+		loadMySessions,
+		loadSession,
+		confirmSession,
+		noShowSession,
+		cancelSession,
+
+		// media
+		uploadMedia,
+
+		// my responses
+		myResponses,
+		loadMyResponses,
+
+		// helpers
+		resetErrors,
+	};
+}
+
+export type PlaytestResponseComposable = ReturnType<typeof usePlaytestResponse>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mundogamernetwork/shared-ui",
-  "version": "1.1.96",
+  "version": "1.2.0",
   "description": "Mundo Gamer Network - Shared UI Layer (Nuxt 3)",
   "type": "module",
   "main": "./nuxt.config.ts",
@@ -28,8 +28,8 @@
     "build": "nuxi build .playground"
   },
   "peerDependencies": {
-    "@pinia/nuxt": ">=0.5.0",
     "@pinia-plugin-persistedstate/nuxt": ">=1.0.0",
+    "@pinia/nuxt": ">=0.5.0",
     "axios": ">=1.0.0",
     "laravel-echo": ">=1.15.0",
     "nuxt": ">=3.13.0",
@@ -38,7 +38,14 @@
     "vue": ">=3.5.0"
   },
   "devDependencies": {
+    "@pinia-plugin-persistedstate/nuxt": "^1.2.1",
+    "@pinia/nuxt": "^0.5.5",
+    "axios": "^1.18.1",
+    "laravel-echo": "^2.3.7",
     "nuxt": "^3.15.4",
-    "typescript": "^5.0.0"
+    "pinia": "^2.3.1",
+    "pusher-js": "^8.5.0",
+    "typescript": "^5.0.0",
+    "vue-tsc": "^2.2.0"
   }
 }