@edpire/sdk 0.5.0

package/dist/index.d.mts

@@ -0,0 +1,430 @@
+import { QuestionRuntimeProps, RuntimeAnswer } from '@youssefalmia/edpire-runtime';
+export { BlankChoiceAnswer, ChoiceSetAnswer, MatchingConnection, MatchingSetAnswer, OpenResponseAnswer, RuntimeAnswer, TypedBlankAnswer } from '@youssefalmia/edpire-runtime';
+import { RichContent } from '@youssefalmia/edpire-schema/authoring';
+
+/**
+ * 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;
+}
+type NodeDetail = {
+    type: "choiceSet";
+    correctChoiceIds: string[];
+} | {
+    type: "matchingSet";
+    pairFeedback: Array<{
+        leftId: string;
+        rightId: string;
+        correct: boolean;
+    }>;
+    correctPairings: Array<{
+        leftId: string;
+        rightId: string;
+    }>;
+};
+interface NodeFeedback {
+    nodeId: string;
+    status: "correct" | "partial" | "incorrect" | "awaiting_review";
+    score: number;
+    maxScore: number;
+    feedback?: string;
+    displayAnswer?: string;
+    detail?: NodeDetail;
+    teacherFeedback?: RichContent[];
+}
+interface QuestionFeedback {
+    questionId: string;
+    nodeResults: NodeFeedback[];
+}
+interface ExerciseFeedbackData {
+    exerciseId: string;
+    questions: QuestionFeedback[];
+}
+interface SubmitResult {
+    submissionId: string;
+    totalScore: number;
+    maxScore: number;
+    percentage: number;
+    passed: boolean;
+    /** If null/undefined, the shell hides the "View Full Report" button. */
+    returnUrl?: string | null;
+    exerciseFeedback: ExerciseFeedbackData[];
+    /** When true, score banners hide the score (still being reviewed). */
+    awaitingManualGrading?: boolean;
+}
+
+type SpinnerTheme = "default" | "dots" | "pulse" | "bars";
+interface GradingOverlayProps {
+    visible: boolean;
+    bgColor?: string;
+    accentColor?: string;
+    text?: string;
+    aiText?: string;
+    spinnerTheme?: SpinnerTheme;
+    animationUrl?: string;
+    hasAiNodes?: boolean;
+    contained?: boolean;
+}
+type OverlayConfig = Pick<GradingOverlayProps, "bgColor" | "accentColor" | "text" | "spinnerTheme" | "animationUrl">;
+
+/**
+ * Standalone, dependency-free i18n for the SDK shell.
+ *
+ * Replaces the web app's `useTranslations("learner.taking")` so the shell can
+ * be rendered in any React environment (Vite, CRA, Astro, UMD CDN, mobile
+ * WebView). Locale is passed as a prop — there is no React context to set up.
+ *
+ * Strings mirror `packages/i18n/messages/{en,fr,ar}.json` under `learner.taking.*`.
+ * Keep in sync if those copies are edited.
+ */
+type ShellLocale = "en" | "fr" | "ar";
+
+/**
+ * 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;
+    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;
+                    }>;
+                };
+            }>;
+        }>;
+    }>;
+}
+interface EmbedError {
+    code: "TOKEN_INVALID" | "TOKEN_EXPIRED" | "TOKEN_USED" | "ORIGIN_NOT_ALLOWED" | "ASSESSMENT_NOT_FOUND" | "MAX_ATTEMPTS_REACHED" | "NETWORK_ERROR" | "UNKNOWN";
+    message: string;
+}
+interface MountOptions {
+    /**
+     * The embed token received from POST /api/v1/embed/token.
+     * Pass this from your server to the browser — do not hardcode.
+     */
+    token: string;
+    /**
+     * Where to mount the assessment player.
+     * CSS selector string or DOM element.
+     */
+    container: string | HTMLElement;
+    /**
+     * Base URL of the Edpire instance. Defaults to "https://edpire.com".
+     * Override for self-hosted or staging environments.
+     */
+    baseUrl?: string;
+    /**
+     * Locale for the assessment player UI. Defaults to "en".
+     * Right-to-left layout is applied automatically for "ar".
+     */
+    locale?: ShellLocale;
+    /**
+     * Branding overrides. By default the SDK loads the assessment's org branding
+     * (logo, colors, fonts) automatically. Pass this to override per-deployment
+     * — useful for white-labelling.
+     */
+    branding?: TakeBranding;
+    /**
+     * When set, the post-submit "View Full Report" button redirects the browser
+     * to this URL with `?submission_id=...&score=...&max_score=...` appended.
+     * Omit to hide the button (consumers can still react via onComplete).
+     */
+    returnUrl?: string;
+    /** Custom label for the post-submit redirect button. */
+    reportLabel?: string;
+    /** Called when the learner clicks the back button. Shown only BEFORE submission. */
+    onBack?: () => void;
+    /** Custom label for the back button. */
+    backLabel?: string;
+    /** Customise the grading overlay (branded spinner, animation URL, etc.). */
+    overlayConfig?: OverlayConfig;
+    /**
+     * Media upload handler — required if the assessment contains OpenResponse
+     * questions with file-upload or recording modes.
+     */
+    mediaHandler?: QuestionRuntimeProps["mediaHandler"];
+    /**
+     * Called when the learner successfully submits the assessment.
+     */
+    onComplete?: (result: EmbedResult) => void;
+    /**
+     * Called when a non-recoverable error occurs.
+     */
+    onError?: (error: EmbedError) => void;
+}
+interface EmbedInstance {
+    /** Unmounts the assessment player and cleans up event listeners. */
+    unmount: () => void;
+}
+interface RenderQuestionOptions {
+    /**
+     * DOM element or CSS selector string to mount into.
+     */
+    container: string | HTMLElement;
+    /**
+     * ContentAST from GET /api/v1/assessments/{id} → exercises[n].questions[n].content_ast
+     */
+    content: unknown;
+    /**
+     * Called on every answer change.
+     */
+    onAnswersChange?: (answers: RuntimeAnswer[]) => void;
+    /**
+     * Feedback from POST /check. Pass the `feedback` field directly.
+     */
+    feedback?: Record<string, unknown> | null;
+    /**
+     * Pre-fill answers.
+     */
+    initialAnswers?: RuntimeAnswer[];
+    /**
+     * Text direction for the question container.
+     */
+    dir?: "ltr" | "rtl";
+}
+interface QuestionInstance {
+    /**
+     * Replace the current question's content.
+     * Also clears feedback — ready for the next question.
+     */
+    setContent(content: unknown): void;
+    /**
+     * Update the feedback state (e.g. after POST /check).
+     * Pass null to clear.
+     */
+    setFeedback(feedback: Record<string, unknown> | null): void;
+    /**
+     * Pre-fill answers (e.g. when navigating back to a previous question).
+     */
+    setInitialAnswers(answers: RuntimeAnswer[]): void;
+    /**
+     * Unmount the React root and clean up.
+     */
+    unmount(): void;
+}
+
+/** 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;
+    type: string;
+    status: string;
+    share_code: string | null;
+    settings: Record<string, unknown>;
+    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[];
+
+declare function renderQuestion(options: RenderQuestionOptions): QuestionInstance;
+
+declare const EdpireAssessment: {
+    /**
+     * Mount an Edpire assessment into the given container.
+     *
+     * @param options - Configuration including the embed token and container element.
+     * @returns An EmbedInstance with an `unmount()` method.
+     *
+     * @example
+     * const embed = EdpireAssessment.mount({
+     *   token: serverSuppliedToken,
+     *   container: document.getElementById("assessment-root"),
+     *   onComplete: (result) => console.log("Score:", result.percentage),
+     *   onError: (err) => console.error(err.message),
+     * })
+     */
+    mount(options: MountOptions): EmbedInstance;
+};
+
+export { EdpireAssessment, type EmbedError, type EmbedInstance, type EmbedResult, type ExerciseFeedbackData, type FlatStep, type MountOptions, type OverlayConfig, type QuestionInstance, type RenderQuestionOptions, type ShellLocale, type SpinnerTheme, type StoredAnswer, type SubmitResult, type TakeBranding, buildSubmitPayload, flattenAssessment, renderQuestion };