@edpire/sdk 0.7.0 → 0.8.1

package/CHANGELOG.md

@@ -9,6 +9,83 @@ integrators pin a version and had no way to tell what a bump would change.
 The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and
 the package follows [semantic versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.8.1] - 2026-09-29
+
+### Fixed
+
+- **An AI-marked answer that has no mark yet is no longer described as a
+  teacher reviewing open responses.** When the AI does not answer in time, the
+  player's banner now says the answers are still being marked ("Being marked",
+  in en/fr/ar), and still hides the score. Driven by the new `ai_pending` field
+  of the submit and review responses; older servers that do not send it keep
+  the previous banner.
+
+### Added
+
+- `ai_pending?: boolean` on `EmbedResult`, on `SubmissionReview.submission`,
+  and on `GradeResult` (`POST /assessments/{id}/submit`). True when an
+  AI-marked answer has no mark yet: treat the score as provisional, never as a
+  final 0.
+
+## [0.8.0] - 2026-09-23
+
+### Added
+
+- **`EdpireAssessment.review({ review, container })`**: reopens a finished
+  attempt as the corrected paper. The learner's answers are replayed into
+  locked questions, with every mark, the expected answer on anything missed,
+  and the teacher's comments on open responses. It is the screen the player
+  shows on submit, available again afterwards.
+
+  ```javascript
+  const review = await fetch(`/api/attempts/${id}/review`).then((r) => r.json())
+  EdpireAssessment.review({ review, container: "#paper" })
+  ```
+
+  `review` is the response of the new `GET /api/v1/submissions/{id}/review`,
+  passed through unchanged. Your server fetches it with an API key after
+  checking ownership, so there is no token and no browser request to Edpire,
+  and the origin allow-list does not apply.
+
+- **`flattenReview(review)`**: the same attempt as one step per question, for
+  flows that show one question per screen. Each step carries the content, the
+  learner's answers, feedback in `/check`'s shape, the score and a status, plus
+  the exercise's shared context. Pure, so also in `@edpire/sdk/core` and on the
+  CDN global.
+
+  ```javascript
+  const steps = flattenReview(review)
+  renderQuestion({ container, content: steps[i].content, initialAnswers: steps[i].answers,
+                   feedback: steps[i].feedback, readOnly: true })
+  ```
+
+- **`readOnly`** on `renderQuestion()` and `EdpireQuestion`: answers show but
+  cannot change.
+
+- **`EdpireClient.getSubmissionReview(id, { learnerRef })`** for that fetch.
+  With `learnerRef`, a submission belonging to anyone else is a 404.
+
+- **`EdpireClient.getLearnerResults(ref, { assessmentId })`**: one
+  assessment's attempt history.
+
+- **`AssessmentShellProps.review`** and the **`ShellReview`** type, for React
+  consumers rendering the shell directly. **`SubmissionReview`**,
+  **`ReviewOptions`** and **`ReviewStep`** types.
+
+- **`teacher_feedback`** on `EmbedResult` node results. Only ever present in a
+  review: at submit time no teacher has marked anything yet.
+
+### Changed
+
+- The back button (`onBack`) now also shows in review mode. Before submission it
+  behaves as before.
+
+### Notes for integrators
+
+No breaking changes. Review needs the new endpoint, which is live on
+edpire.com from this release. See the attempt history guide:
+https://docs.edpire.com/developer/attempt-history
+
 ## [0.7.0] - 2026-09-22
 
 ### Added

package/README.md

@@ -90,7 +90,7 @@ embed.unmount()
 **CDN (no bundler):**
 
 ```html
-<script src="https://cdn.jsdelivr.net/npm/@edpire/sdk@0.7.0/dist/umd/index.global.js"></script>
+<script src="https://cdn.jsdelivr.net/npm/@edpire/sdk@0.8.1/dist/umd/index.global.js"></script>
 <script>
   EdpireSDK.EdpireAssessment.mount({ token, container: "#root", onComplete: handleDone })
 </script>
@@ -248,6 +248,18 @@ If omitted, rate limiting falls back to `learner_ref`, which accumulates across
 
 **Required API key scopes:** `read:assessments` (for fetching and checking) + `write:submissions` (for the final submit).
 
+**Reviewing a past attempt, one question at a time** (since 0.8.0): fetch it on your server with `client.getSubmissionReview(id, { learnerRef })`, then in the browser:
+
+```typescript
+const steps = flattenReview(review)
+renderQuestion({
+  container, content: steps[i].content,
+  initialAnswers: steps[i].answers, feedback: steps[i].feedback, readOnly: true,
+})
+```
+
+For the whole attempt at once: `EdpireAssessment.review({ review, container })`. See the [attempt history guide](https://docs.edpire.com/developer/attempt-history).
+
 **When to use:** You want full control over pacing, navigation, animations, or scoring UX. You're building a Duolingo-style flow, a timed drill, a practice mode, or any experience that goes beyond a linear "answer all → submit" form.
 
 ---
@@ -316,7 +328,7 @@ The integration uses two parts:
 </head>
 <body>
   <div id="root"></div>
-  <script src="https://cdn.jsdelivr.net/npm/@edpire/sdk@0.7.0/dist/umd/index.global.js"></script>
+  <script src="https://cdn.jsdelivr.net/npm/@edpire/sdk@0.8.1/dist/umd/index.global.js"></script>
   <script>
     EdpireSDK.EdpireAssessment.mount({
       token: "{{EMBED_TOKEN}}",   // replace server-side before loading

package/dist/client.d.mts

@@ -1,4 +1,5 @@
 import { RuntimeAnswer } from '@youssefalmia/edpire-runtime';
+import { RichContent } from '@youssefalmia/edpire-schema/authoring';
 
 /** Flat per-question answer collected during a custom player session. */
 interface StoredAnswer {
@@ -10,6 +11,195 @@ interface StoredAnswer {
     answers: RuntimeAnswer[];
 }
 
+/**
+ * Public types for the polished Assessment Shell.
+ *
+ * The shell renders the same UI used at edpire.com's hosted player.
+ * Consumers using the EdpireAssessment.mount() API get these types
+ * indirectly via MountOptions; consumers rendering <AssessmentShell>
+ * directly import them from "@edpire/sdk/react".
+ */
+
+/** Branding payload accepted by AssessmentShell. Mirrors what edpire.com sends. */
+interface TakeBranding {
+    /** Org display name — shown as the alt text on the logo. */
+    name: string;
+    /** Logo URL (any https URL). When absent, the Edpire logo is shown. */
+    logoUrl: string | null;
+    branding: {
+        /** CSS color for the primary action buttons (Submit, View Report, etc.). */
+        primaryColor?: string;
+        /** CSS color used as the background of the top bar and per-exercise headers. */
+        accentColor?: string;
+        /** font-family applied to the shell. Pair with `fontUrl` for non-system fonts. */
+        fontFamily?: string;
+        /** A Google Fonts stylesheet URL; the shell injects a <link> tag at mount. */
+        fontUrl?: string;
+        /** When false, the "Powered by Edpire" watermark is hidden. Default true. */
+        showPoweredBy?: boolean;
+    } | null;
+}
+
+/**
+ * Public types for the Edpire Embeddable JS SDK.
+ */
+
+type NodeFeedbackStatus = "correct" | "partial" | "incorrect" | "awaiting_review";
+interface EmbedResult {
+    submission_id: string;
+    score: number;
+    max_score: number;
+    percentage: number;
+    passed: boolean;
+    passing_score_percent: number;
+    attempt_number: number;
+    /** True when the submission contains open-response nodes still pending teacher review. */
+    awaiting_manual_grading?: boolean;
+    /** True when an AI-marked answer has no mark yet: it is being marked, not scored 0. */
+    ai_pending?: boolean;
+    exercise_results: Array<{
+        exercise_id: string;
+        total_score: number;
+        max_score: number;
+        question_results: Array<{
+            question_id: string;
+            score: number;
+            correct: boolean;
+            points: number;
+        }>;
+    }>;
+    exercise_feedback: Array<{
+        exercise_id: string;
+        questions: Array<{
+            question_id: string;
+            node_results: Array<{
+                node_id: string;
+                status: NodeFeedbackStatus;
+                score: number;
+                max_score: number;
+                feedback?: string;
+                display_answer?: string;
+                detail?: {
+                    type: "choiceSet";
+                    correctChoiceIds: string[];
+                } | {
+                    type: "matchingSet";
+                    pairFeedback: Array<{
+                        leftId: string;
+                        rightId: string;
+                        correct: boolean;
+                    }>;
+                    correctPairings: Array<{
+                        leftId: string;
+                        rightId: string;
+                    }>;
+                };
+                /**
+                 * The teacher's written feedback on an open response. Only ever present
+                 * in a review (`GET /submissions/{id}/review`), since at submit time no
+                 * teacher has graded anything yet.
+                 */
+                teacher_feedback?: RichContent[];
+            }>;
+        }>;
+    }>;
+}
+/**
+ * Response of `GET /api/v1/submissions/{id}/review`: one finished attempt, with
+ * everything needed to draw it as the corrected paper. Fetch it on your server
+ * (it needs an API key with `read:results`), send it to the browser, and pass it
+ * to `EdpireAssessment.review()` unchanged.
+ */
+interface SubmissionReview {
+    submission: {
+        id: string;
+        assessment_id: string;
+        learner_ref: string | null;
+        status: string;
+        attempt_number: number;
+        /** How many attempts this learner has made at this assessment, this one included. */
+        total_attempts: number;
+        score: number;
+        max_score: number;
+        percentage: number;
+        passed: boolean;
+        passing_score_percent: number;
+        is_fully_graded: boolean;
+        /**
+         * True while a teacher still has open responses to grade. `score`,
+         * `percentage` and `passed` are provisional until it turns false, and the
+         * player hides them.
+         */
+        awaiting_manual_grading: boolean;
+        /** True while an AI-marked answer has no mark yet. Optional: older servers did not send it. */
+        ai_pending?: boolean;
+        submitted_at: string | null;
+    };
+    assessment: AssessmentLoaderResponse["assessment"];
+    meta: Omit<AssessmentLoaderResponse["meta"], "type">;
+    branding?: TakeBranding | null;
+    /** The learner's answers, in the shape the player collected them. */
+    answers: {
+        exerciseAnswers: Array<{
+            exerciseId: string;
+            questionAnswers: Array<{
+                questionId: string;
+                answers: RuntimeAnswer[];
+            }>;
+        }>;
+    };
+    exercise_feedback: EmbedResult["exercise_feedback"];
+}
+interface AssessmentLoaderResponse {
+    assessment: {
+        /**
+         * Assessment-level annex — reading texts, figures, formula sheets. The
+         * player shows it as a side panel on wide screens and a drawer on narrow
+         * ones. Null when the assessment has none.
+         */
+        annex?: unknown | null;
+        exercises: Array<{
+            id: string;
+            sharedContext: unknown | null;
+            questions: Array<{
+                id: string;
+                version: "1.0";
+                content: unknown;
+                /** Sent by the content loader, not by a review. Nothing in the player reads either. */
+                points?: number;
+                sequenceNumber?: number;
+                answerKeys: never[];
+            }>;
+        }>;
+    };
+    meta: {
+        id: string;
+        title: string;
+        type: string;
+        category?: string | null;
+        /**
+         * The assessment's learner-facing language, which also decides text
+         * direction. The player uses this unless the host passes `locale`
+         * explicitly, so a French assessment reads left-to-right even when embedded
+         * in a right-to-left product.
+         */
+        language?: "en" | "fr" | "ar";
+        settings: {
+            time_limit_minutes: number | null;
+            passing_score_percent: number;
+            allowed_attempts: number;
+            show_solutions: string;
+        };
+    };
+    attempt_info: {
+        attempt_number: number;
+        can_retry: boolean;
+        attempts_remaining: number | null;
+    };
+    /** Org branding loaded server-side. May be overridden by MountOptions.branding. */
+    branding?: TakeBranding | null;
+}
+
 /**
  * @edpire/sdk/client — Server-side API client for Edpire.
  *
@@ -146,6 +336,12 @@ interface GradeResult {
      * the `submission.grading.completed` webhook.
      */
     awaiting_manual_grading: boolean;
+    /**
+     * True when an AI-marked answer has no mark yet (the AI did not answer in
+     * time). It is being marked, not scored 0: treat the score as provisional.
+     * Optional because servers before 2026-09-29 did not send it.
+     */
+    ai_pending?: boolean;
     exercise_results: Array<{
         exercise_id: string;
         total_score: number;
@@ -193,6 +389,13 @@ interface CheckResult {
     correct: boolean;
     score: number;
     max_score: number;
+    /**
+     * True when an AI-graded part of the question could not be graded in time.
+     * That node's feedback carries `pending: true` and no score, and `correct` /
+     * `score` cover only what was graded. Not a wrong answer: do not penalise it.
+     * Optional because servers before 2026-09-29 did not send it.
+     */
+    ai_pending?: boolean;
     feedback: Record<string, unknown>;
 }
 interface Submission {
@@ -345,16 +548,33 @@ declare class EdpireClient {
      * @throws {EdpireError} 404 if not found, 401/403 for auth issues.
      */
     getSubmission(id: string): Promise<Submission>;
+    /**
+     * Fetch one finished attempt as the corrected paper: content, the learner's
+     * answers and the marking. Send the result to the browser and pass it to
+     * `EdpireAssessment.review()` unchanged.
+     *
+     * @param id - Submission UUID.
+     * @param params.learnerRef - The learner you believe owns it. When given, a
+     *   submission belonging to anyone else is a 404, so a bug in your own
+     *   ownership check cannot show one learner another's paper. Always pass it.
+     * @throws {EdpireError} 404 (not found, or not this learner's), 409 (not
+     *   submitted yet, or the assessment has been unpublished since).
+     */
+    getSubmissionReview(id: string, params?: {
+        learnerRef?: string;
+    }): Promise<SubmissionReview>;
     /**
      * Fetch all submissions for a learner.
      *
      * @param learnerRef - Your stable user ID (the `learner_ref` you passed during submit).
+     * @param params.assessmentId - Only this assessment's attempts.
      * @param params.page - Page number (default 1).
      * @param params.limit - Items per page (default 50, max 100).
      * @returns Paginated list of submissions.
      * @throws {EdpireError} 401/403 for auth issues.
      */
     getLearnerResults(learnerRef: string, params?: {
+        assessmentId?: string;
         page?: number;
         limit?: number;
     }): Promise<PaginatedResponse<Submission>>;
@@ -528,4 +748,4 @@ declare function createEdpireTokenHandler(opts: EdpireTokenHandlerOptions): (req
  */
 declare function toNodeHandler(handler: (req: Request) => Promise<Response>): (req: ConnectRequest, res: ConnectResponse) => void;
 
-export { type Assessment, type AssessmentExercise, type AssessmentQuestion, type AssessmentSummary, type CheckOptions, type CheckResult, EdpireClient, type EdpireClientOptions, EdpireError, type EdpireTokenHandlerOptions, type EmbedToken, type GradeResult, type PaginatedResponse, type StoredAnswer, type Submission, type SubmitOptions, type Webhook, type WebhookWithSecret, createEdpireTokenHandler, toNodeHandler };
+export { type Assessment, type AssessmentExercise, type AssessmentQuestion, type AssessmentSummary, type CheckOptions, type CheckResult, EdpireClient, type EdpireClientOptions, EdpireError, type EdpireTokenHandlerOptions, type EmbedToken, type GradeResult, type PaginatedResponse, type StoredAnswer, type Submission, type SubmissionReview, type SubmitOptions, type Webhook, type WebhookWithSecret, createEdpireTokenHandler, toNodeHandler };

package/dist/client.mjs

@@ -182,10 +182,27 @@ var EdpireClient = class {
   async getSubmission(id) {
     return this.request("GET", `/submissions/${id}`);
   }
+  /**
+   * Fetch one finished attempt as the corrected paper: content, the learner's
+   * answers and the marking. Send the result to the browser and pass it to
+   * `EdpireAssessment.review()` unchanged.
+   *
+   * @param id - Submission UUID.
+   * @param params.learnerRef - The learner you believe owns it. When given, a
+   *   submission belonging to anyone else is a 404, so a bug in your own
+   *   ownership check cannot show one learner another's paper. Always pass it.
+   * @throws {EdpireError} 404 (not found, or not this learner's), 409 (not
+   *   submitted yet, or the assessment has been unpublished since).
+   */
+  async getSubmissionReview(id, params) {
+    const query = params?.learnerRef ? `?learner_ref=${encodeURIComponent(params.learnerRef)}` : "";
+    return this.request("GET", `/submissions/${id}/review${query}`);
+  }
   /**
    * Fetch all submissions for a learner.
    *
    * @param learnerRef - Your stable user ID (the `learner_ref` you passed during submit).
+   * @param params.assessmentId - Only this assessment's attempts.
    * @param params.page - Page number (default 1).
    * @param params.limit - Items per page (default 50, max 100).
    * @returns Paginated list of submissions.
@@ -194,6 +211,7 @@ var EdpireClient = class {
   async getLearnerResults(learnerRef, params) {
     const query = new URLSearchParams();
     query.set("learner_ref", learnerRef);
+    if (params?.assessmentId) query.set("assessment_id", params.assessmentId);
     if (params?.page) query.set("page", String(params.page));
     if (params?.limit) query.set("limit", String(params.limit));
     return this.requestPaginated(