@edpire/sdk 0.6.5 → 0.6.7

package/README.md

@@ -90,7 +90,7 @@ embed.unmount()
 **CDN (no bundler):**
 
 ```html
-<script src="https://cdn.jsdelivr.net/npm/@edpire/sdk@0.6.5/dist/umd/index.global.js"></script>
+<script src="https://cdn.jsdelivr.net/npm/@edpire/sdk@0.6.7/dist/umd/index.global.js"></script>
 <script>
   EdpireSDK.EdpireAssessment.mount({ token, container: "#root", onComplete: handleDone })
 </script>
@@ -310,7 +310,7 @@ The integration uses two parts:
 </head>
 <body>
   <div id="root"></div>
-  <script src="https://cdn.jsdelivr.net/npm/@edpire/sdk@0.6.5/dist/umd/index.global.js"></script>
+  <script src="https://cdn.jsdelivr.net/npm/@edpire/sdk@0.6.7/dist/umd/index.global.js"></script>
   <script>
     EdpireSDK.EdpireAssessment.mount({
       token: "{{EMBED_TOKEN}}",   // replace server-side before loading

package/dist/core.d.mts

@@ -0,0 +1,149 @@
+import { RuntimeAnswer } from '@youssefalmia/edpire-runtime';
+
+/** Flat per-question answer collected during a custom player session. */
+interface StoredAnswer {
+    /** Exercise ID — from the `exerciseId` field on each `FlatStep`. */
+    exerciseId: string;
+    /** Question ID — from the `questionId` field on each `FlatStep`. */
+    questionId: string;
+    /** Answers collected from `EdpireQuestion`'s `onAnswersChange` callback. */
+    answers: RuntimeAnswer[];
+}
+/**
+ * Convert a flat array of per-question answers into the nested structure
+ * expected by `EdpireClient.submit()` and `POST /api/v1/assessments/{id}/submit`.
+ *
+ * This is the bridge between the simple flat collection pattern used in custom
+ * players and the grouped format the API requires.
+ *
+ * @example
+ * ```typescript
+ * import { flattenAssessment, buildSubmitPayload } from "@edpire/sdk"
+ * import type { StoredAnswer } from "@edpire/sdk"
+ *
+ * const stored: StoredAnswer[] = []
+ *
+ * // During the session, after each question:
+ * stored.push({ exerciseId: step.exerciseId, questionId: step.questionId, answers })
+ *
+ * // At the end, submit:
+ * const payload = buildSubmitPayload(stored)
+ * await client.submit(assessmentId, { learner_ref: userId, answers: payload })
+ *
+ * // Or pass the flat array directly — client.submit() accepts both formats:
+ * await client.submit(assessmentId, { learner_ref: userId, answers: stored })
+ * ```
+ */
+declare function buildSubmitPayload(stored: StoredAnswer[]): {
+    exerciseAnswers: Array<{
+        exerciseId: string;
+        questionAnswers: Array<{
+            questionId: string;
+            answers: RuntimeAnswer[];
+        }>;
+    }>;
+};
+
+/**
+ * @edpire/sdk/client — Server-side API client for Edpire.
+ *
+ * Node.js only. Zero browser dependencies. Uses native fetch (Node 18+).
+ *
+ * @example
+ * ```typescript
+ * import { EdpireClient } from "@edpire/sdk/client"
+ *
+ * const client = new EdpireClient({
+ *   apiKey: process.env.EDPIRE_API_KEY!,
+ *   baseUrl: "https://edpire.com",
+ * })
+ *
+ * const assessments = await client.getAssessments({ status: "published" })
+ * const result = await client.submit("assessment-id", {
+ *   learner_ref: "user-123",
+ *   answers: { exerciseAnswers: [...] },
+ * })
+ * ```
+ */
+
+/** Assessment summary returned by getAssessments() (list). Does not include exercises. */
+interface AssessmentSummary {
+    id: string;
+    title: string;
+    description: string | null;
+    /**
+     * Free-form label (max 80 chars), set by the author. Replaces the old
+     * `type: "quiz" | "exam" | "practice"` enum, which the API never returned.
+     */
+    category: string | null;
+    status: string;
+    share_code: string | null;
+    settings: Record<string, unknown>;
+    /** Sum of answer-key max scores. Use this to normalize scores, not the sum of `points`. */
+    max_score?: number;
+    /** Present on the list endpoint only, not on a single-assessment fetch. */
+    exercise_count?: number;
+    created_at: string;
+    updated_at: string;
+}
+/** Full assessment returned by getAssessment() (single fetch). Always includes exercises. */
+interface Assessment extends AssessmentSummary {
+    exercises: AssessmentExercise[];
+}
+interface AssessmentExercise {
+    id: string;
+    shared_context: unknown | null;
+    questions: AssessmentQuestion[];
+}
+interface AssessmentQuestion {
+    id: string;
+    content_ast: unknown;
+    points: number;
+    sequence_number: number;
+}
+
+/**
+ * flattenAssessment — convert an assessment API response into a linear
+ * sequence of steps, one per question.
+ *
+ * Useful for Duolingo-style flows where you present questions one at a time
+ * and need to know the exercise context of each step (for POST /check).
+ *
+ * @example
+ * const res = await fetch(`/api/v1/assessments/${id}`, { headers: { Authorization: `Bearer ${key}` } })
+ * const { data: assessment } = await res.json()
+ *
+ * const steps = flattenAssessment(assessment)
+ * // steps[0] = { exerciseId, questionId, content, points, sequenceNumber, index: 0 }
+ *
+ * // Render step:
+ * <EdpireQuestion content={steps[currentIndex].content} ... />
+ *
+ * // Check step:
+ * POST /api/v1/assessments/{id}/check { exercise_id: steps[i].exerciseId, question_id: steps[i].questionId, ... }
+ */
+
+interface FlatStep {
+    /** The exercise this question belongs to — required for POST /check */
+    exerciseId: string;
+    /** The question ID — required for POST /check */
+    questionId: string;
+    /** ContentAST — pass directly to EdpireQuestion's `content` prop */
+    content: unknown;
+    /** Point value of this question */
+    points: number;
+    /** Original sequence number within its exercise */
+    sequenceNumber: number;
+    /** 0-based index in the flattened sequence — use for progress bar */
+    index: number;
+}
+/**
+ * Flatten an assessment from getAssessment() / GET /api/v1/assessments/{id}
+ * into an ordered array of steps, preserving exercise and position information.
+ *
+ * The order follows the assessment's exercise order, then question order
+ * within each exercise — the same order a learner would see them.
+ */
+declare function flattenAssessment(assessment: Assessment): FlatStep[];
+
+export { type FlatStep, type StoredAnswer, buildSubmitPayload, flattenAssessment };

package/dist/core.mjs

@@ -0,0 +1 @@
+function i(r){let s=[],e=0;for(let t of r.exercises)for(let n of t.questions)s.push({exerciseId:t.id,questionId:n.id,content:n.content_ast,points:n.points,sequenceNumber:n.sequence_number,index:e++});return s}function o(r){let s=new Map;for(let e of r)s.has(e.exerciseId)||s.set(e.exerciseId,[]),s.get(e.exerciseId).push({questionId:e.questionId,answers:e.answers});return{exerciseAnswers:Array.from(s.entries()).map(([e,t])=>({exerciseId:e,questionAnswers:t}))}}export{o as buildSubmitPayload,i as flattenAssessment};