@superapp_men/submit-assessment-results 1.0.0

package/README.md

@@ -0,0 +1,196 @@
+# @superapp_men/submit-assessment-results
+
+Package for **partner applications** (running inside the SuperApp iframe or Capacitor WebView) to submit assessment results to the SuperApp. The SuperApp forwards the payload to the `SubmitAssessmentResults` backend endpoint (adding `academicYearId` and `periodWeekSubjectId`) and returns the **exact backend response** to the partner.
+
+## Features
+
+- **Builder / factory** to construct skills and questions data in a type-safe way.
+- **Client-side validation** before calling the SuperApp: the same rules as the backend `SubmitAssessmentResultsValidator` run first. Invalid payloads get immediate `400`-style errors with field-level messages without a round-trip.
+- **No `academicYearId` or `periodWeekSubjectId`** in the partner payload — the SuperApp adds them when calling the API.
+- **Exact backend response** returned: success (200), validation errors (400), functional errors (422), and technical errors (404, 409, 429, 500).
+
+**Current limitation (upcoming feature):** `subSkills` must be `null` or an empty array `[]`. Sub-skills are not yet supported; each skill must use `questions` only. Support for nested sub-skills will be added in a future release.
+
+## Installation
+
+```bash
+npm install @superapp_men/submit-assessment-results
+```
+
+## Usage (Partner App)
+
+Each skill must contain **questions** (not sub-skills). The `subSkills` property must be omitted, `null`, or an empty array `[]`; non-empty `subSkills` will fail validation until the feature is released.
+
+### 1. Build payload with the builder
+
+```ts
+import {
+  AssessmentSubmissionClient,
+  AssessmentSubmission,
+  QuestionRole,
+} from "@superapp_men/submit-assessment-results";
+
+const skill1 = AssessmentSubmission.skill("MATH_ADD_01", 1, true)
+  .questions([
+    AssessmentSubmission.question("Q001", true, QuestionRole.VALIDATION)
+      .order(1)
+      .responseTime(5000)
+      .build(),
+    AssessmentSubmission.question("Q002", false, QuestionRole.VALIDATION)
+      .order(2)
+      .build(),
+  ])
+  .build();
+
+const payload = AssessmentSubmission.builder()
+  .setStudentId("3fa85f64-5717-4562-b3fc-2c963f66afa6")
+  .setPartnerCode("PARTNER001")
+  .setAttemptId("unique-attempt-id-12345")
+  .setAser(false)
+  .setTotalSkillsInWeek(10)
+  .addSkill(skill1)
+  .build();
+```
+
+### 2. Adding multiple skills (e.g. 3 skills)
+
+Use **`addSkill()`** for each skill or **`addSkills()`** with an array.
+
+**Option A — One `addSkill()` per skill:**
+
+```ts
+const skill1 = AssessmentSubmission.skill("MATH_ADD_01", 1, true)
+  .questions([
+    AssessmentSubmission.question("Q001", true, QuestionRole.VALIDATION).order(1).build(),
+    AssessmentSubmission.question("Q002", false, QuestionRole.VALIDATION).order(2).build(),
+  ])
+  .build();
+
+const skill2 = AssessmentSubmission.skill("MATH_SUB_01", 2, true)
+  .questions([
+    AssessmentSubmission.question("Q003", true, QuestionRole.VALIDATION).order(1).build(),
+    AssessmentSubmission.question("Q004", true, QuestionRole.VALIDATION).order(2).build(),
+  ])
+  .build();
+
+const skill3 = AssessmentSubmission.skill("MATH_MUL_01", 3, false)
+  .questions([
+    AssessmentSubmission.question("Q005", false, QuestionRole.VALIDATION).order(1).build(),
+  ])
+  .build();
+
+const payload = AssessmentSubmission.builder()
+  .setStudentId(studentId)
+  .setPartnerCode("PARTNER001")
+  .setAttemptId("attempt-" + Date.now())
+  .setTotalSkillsInWeek(3)
+  .addSkill(skill1)
+  .addSkill(skill2)
+  .addSkill(skill3)
+  .build();
+```
+
+**Option B — Build an array and use `addSkills()`:**
+
+```ts
+const skills = [
+  AssessmentSubmission.skill("MATH_ADD_01", 1, true)
+    .questions([
+      AssessmentSubmission.question("Q001", true, QuestionRole.VALIDATION).order(1).build(),
+      AssessmentSubmission.question("Q002", false, QuestionRole.VALIDATION).order(2).build(),
+    ])
+    .build(),
+  AssessmentSubmission.skill("MATH_SUB_01", 2, true)
+    .questions([
+      AssessmentSubmission.question("Q003", true, QuestionRole.VALIDATION).order(1).build(),
+    ])
+    .build(),
+  AssessmentSubmission.skill("MATH_MUL_01", 3, false)
+    .questions([
+      AssessmentSubmission.question("Q005", false, QuestionRole.VALIDATION).order(1).build(),
+    ])
+    .build(),
+];
+
+const payload = AssessmentSubmission.builder()
+  .setStudentId(studentId)
+  .setPartnerCode("PARTNER001")
+  .setAttemptId("attempt-" + Date.now())
+  .setTotalSkillsInWeek(3)
+  .addSkills(skills)
+  .build();
+```
+
+Make sure **`setTotalSkillsInWeek(n)`** matches the number of skills you submit (e.g. `3` when you add 3 skills).
+
+### 3. Submit and handle response
+
+`client.submit(payload)` runs **client-side validation** first (same rules as the backend). If validation fails, it returns immediately with `ok: false`, `statusCode: 400`, and `body.errors` (field paths and messages). If validation passes, it sends the payload to the SuperApp and returns the backend response.
+
+```ts
+const client = new AssessmentSubmissionClient({ timeout: 30000, debug: true });
+
+const result = await client.submit(payload);
+
+if (result.ok) {
+  console.log("Success:", result.body.attemptId, result.body.status);
+  // result.body is SubmitAssessmentResultsResponse
+} else {
+  console.log("Error:", result.statusCode, result.body);
+  // result.body is ValidationProblemDetails (400) or ProblemDetails (404/409/422/429/500)
+  if (result.statusCode === 400 && "errors" in result.body) {
+    console.log("Validation errors:", result.body.errors);
+  }
+}
+```
+
+### 4. Optional: validate without submitting
+
+You can run the same validation without sending to the SuperApp (e.g. to show errors in the UI before submit):
+
+```ts
+import { validateSubmitAssessmentPayload, toValidationProblemDetails } from "@superapp_men/submit-assessment-results";
+
+const validation = validateSubmitAssessmentPayload(payload);
+if (!validation.valid) {
+  const details = toValidationProblemDetails(validation.errors);
+  console.log("Validation errors:", details.errors); // Record<path, string[]>
+}
+```
+
+## API
+
+- **`AssessmentSubmission.builder()`** — Fluent builder for the full partner payload.
+- **`AssessmentSubmission.skill(code, order, passed)`** — Builder for one skill. Use `.questions(...)` only; `.subSkills(...)` with a non-empty array is not yet supported (validation will fail).
+- **`AssessmentSubmission.question(code, isCorrect, questionRole)`** — Builder for one question.
+- **`new AssessmentSubmissionClient(config)`** — Client with `submit(payload)` returning `Promise<SubmitAssessmentResultsApiResult>`. Runs client-side validation before sending.
+- **`validateSubmitAssessmentPayload(payload)`** — Returns `{ valid, errors }` using the same rules as the backend validator.
+- **`toValidationProblemDetails(errors)`** — Converts `ValidationError[]` to a backend-style `{ status: 400, title, errors }` object.
+- **`SubmitAssessmentResultsApiResult`** — `{ ok: true, statusCode, body }` or `{ ok: false, statusCode, body }` with the exact backend response (or client-side validation errors when invalid).
+
+## SuperApp integration
+
+The SuperApp must:
+
+1. Listen for messages with `type: "assessment:submit-request"`.
+2. Enrich the payload with `academicYearId` and `periodWeekSubjectId`.
+3. Call `POST api/v1.0/submit-results` with the enriched body and forward the HTTP status and response body back to the partner via postMessage with `type: "assessment:submit-response"`.
+
+See the main SuperApp repo for `IframeCommunicationHandler` and the service that calls the SubmitAssessmentResults endpoint.
+
+## Types (superapp entry)
+
+For SuperApp-side code that handles these messages:
+
+```ts
+import type {
+  AssessmentSubmitRequestMessage,
+  AssessmentSubmitResponseMessage,
+  SubmitAssessmentResultsPartnerPayload,
+} from "@superapp_men/submit-assessment-results/superapp";
+import { AssessmentMessageType } from "@superapp_men/submit-assessment-results/superapp";
+```
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,202 @@
+/**
+ * Types for @superapp_men/submit-assessment-results
+ * Aligned with SubmitAssessmentResults API (academicYearId and periodWeekSubjectId
+ * are omitted in partner payload; SuperApp adds them when calling the endpoint).
+ */
+/** Question role in the assessment (matches backend enum). */
+declare enum QuestionRole {
+    POSITIONING = 1,
+    VALIDATION = 2,
+    REMEDIATION = 3,
+    BONUS = 4
+}
+/** Response time: milliseconds (number) or "hh:mm:ss" string. */
+type ResponseTimeInput = number | string;
+/** Single question result (partner payload). */
+interface SubmittedQuestionResultPayload {
+    questionCode: string;
+    isCorrect: boolean;
+    questionOrder: number;
+    questionRole: QuestionRole;
+    responseTime?: ResponseTimeInput;
+    attemptsCount?: number;
+    questionTextFr?: string;
+    questionTextAr?: string;
+}
+/** Single skill result; must have either subSkills or questions. */
+interface SubmittedSkillResultPayload {
+    skillCode: string;
+    skillOrder: number;
+    passed: boolean;
+    titleFr?: string;
+    titleAr?: string;
+    descriptionFr?: string;
+    descriptionAr?: string;
+    subSkills?: SubmittedSkillResultPayload[];
+    questions?: SubmittedQuestionResultPayload[];
+}
+/**
+ * Partner payload for submit assessment results.
+ * academicYearId and periodWeekSubjectId are NOT included; the SuperApp
+ * adds them when calling the backend.
+ */
+interface SubmitAssessmentResultsPartnerPayload {
+    studentId: string;
+    partnerCode: string;
+    attemptId: string;
+    isAser?: boolean;
+    totalSkillsInWeek: number;
+    skills: SubmittedSkillResultPayload[];
+}
+/** Success response from SubmitAssessmentResults endpoint. */
+interface SubmitAssessmentResultsResponse {
+    attemptId: string;
+    isDuplicate: boolean;
+    status: string;
+    message: string | null;
+    serverTimeUtc: string;
+}
+/** ValidationProblemDetails (400). */
+interface ValidationProblemDetails {
+    type?: string;
+    title?: string;
+    status: number;
+    detail?: string;
+    instance?: string;
+    errors?: Record<string, string[]>;
+}
+/** ProblemDetails (404, 409, 422, 429, 500). */
+interface ProblemDetails {
+    type?: string;
+    title?: string;
+    status?: number;
+    detail?: string;
+    instance?: string;
+    [key: string]: unknown;
+}
+/**
+ * Result of calling submit: either the success response or an error response
+ * with statusCode and body as returned by the backend.
+ */
+type SubmitAssessmentResultsApiResult = {
+    ok: true;
+    statusCode: number;
+    body: SubmitAssessmentResultsResponse;
+} | {
+    ok: false;
+    statusCode: number;
+    body: ValidationProblemDetails | ProblemDetails;
+};
+/** Message types for iframe/Capacitor communication. */
+declare enum AssessmentMessageType {
+    REQUEST = "assessment:submit-request",
+    RESPONSE = "assessment:submit-response"
+}
+
+interface AssessmentSubmissionClientConfig {
+    /** Request timeout in ms (default 30000). */
+    timeout?: number;
+    /** Enable debug logs (default false). */
+    debug?: boolean;
+}
+/**
+ * Client for partner applications to submit assessment results to the SuperApp.
+ * Sends the payload via postMessage to the parent (SuperApp); the SuperApp
+ * adds academicYearId and periodWeekSubjectId and calls the backend, then
+ * returns the exact backend response (success, validation errors, functional
+ * errors, or technical errors).
+ */
+declare class AssessmentSubmissionClient {
+    private bridge;
+    private config;
+    constructor(config?: AssessmentSubmissionClientConfig);
+    /**
+     * Submit assessment results. Runs client-side validation first (same rules as backend);
+     * if invalid, returns immediately with statusCode 400 and errors. Otherwise sends to
+     * SuperApp and returns the exact backend response.
+     */
+    submit(payload: SubmitAssessmentResultsPartnerPayload): Promise<SubmitAssessmentResultsApiResult>;
+    setDebug(enabled: boolean): void;
+    destroy(): void;
+}
+
+/**
+ * Fluent builder for a single question result.
+ */
+declare class QuestionResultBuilder {
+    private data;
+    constructor(questionCode: string, isCorrect: boolean, questionRole: QuestionRole);
+    order(questionOrder: number): this;
+    responseTime(value: number | string): this;
+    attemptsCount(count: number): this;
+    questionText(fr?: string, ar?: string): this;
+    build(): SubmittedQuestionResultPayload;
+}
+/**
+ * Fluent builder for a single skill result (with questions or sub-skills).
+ */
+declare class SkillResultBuilder {
+    private data;
+    constructor(skillCode: string, skillOrder: number, passed: boolean);
+    title(titleFr?: string, titleAr?: string): this;
+    description(descriptionFr?: string, descriptionAr?: string): this;
+    questions(questions: SubmittedQuestionResultPayload[]): this;
+    subSkills(subSkills: SubmittedSkillResultPayload[]): this;
+    build(): SubmittedSkillResultPayload;
+}
+/**
+ * Fluent builder for the full partner payload (no academicYearId / periodWeekSubjectId).
+ */
+declare class AssessmentSubmissionBuilder {
+    private studentId;
+    private partnerCode;
+    private attemptId;
+    private isAser;
+    private totalSkillsInWeek;
+    private skills;
+    setStudentId(studentId: string): this;
+    setPartnerCode(partnerCode: string): this;
+    setAttemptId(attemptId: string): this;
+    setAser(isAser: boolean): this;
+    setTotalSkillsInWeek(total: number): this;
+    addSkill(skill: SubmittedSkillResultPayload): this;
+    addSkills(skillList: SubmittedSkillResultPayload[]): this;
+    build(): SubmitAssessmentResultsPartnerPayload;
+}
+/** Factory helpers. */
+declare const AssessmentSubmission: {
+    builder(): AssessmentSubmissionBuilder;
+    skill(skillCode: string, skillOrder: number, passed: boolean): SkillResultBuilder;
+    question(questionCode: string, isCorrect: boolean, questionRole?: QuestionRole): QuestionResultBuilder;
+};
+
+/**
+ * Client-side validation mirroring backend SubmitAssessmentResultsValidator.
+ * Run before sending to SuperApp so partners get immediate validation errors
+ * without a round-trip to the API.
+ */
+
+interface ValidationError {
+    /** Property path (e.g. "StudentId", "Skills[0].SkillCode"). */
+    key: string;
+    message: string;
+}
+interface ValidationResult {
+    valid: boolean;
+    errors: ValidationError[];
+}
+/** Flatten to backend-style errors record (key -> string[]). */
+declare function toValidationProblemDetails(errors: ValidationError[]): {
+    status: number;
+    title: string;
+    errors: Record<string, string[]>;
+};
+/**
+ * Validate the partner payload using the same rules as the backend
+ * SubmitAssessmentResultsValidator. Call this before submit() to get
+ * immediate validation errors without calling the SuperApp/backend.
+ */
+declare function validateSubmitAssessmentPayload(payload: SubmitAssessmentResultsPartnerPayload): ValidationResult;
+
+export { AssessmentMessageType, AssessmentSubmission, AssessmentSubmissionBuilder, AssessmentSubmissionClient, QuestionResultBuilder, QuestionRole, SkillResultBuilder, toValidationProblemDetails, validateSubmitAssessmentPayload };
+export type { AssessmentSubmissionClientConfig, ProblemDetails, ResponseTimeInput, SubmitAssessmentResultsApiResult, SubmitAssessmentResultsPartnerPayload, SubmitAssessmentResultsResponse, SubmittedQuestionResultPayload, SubmittedSkillResultPayload, ValidationError, ValidationProblemDetails, ValidationResult };