@edpire/sdk 0.5.0 → 0.6.1

package/dist/react.d.mts

@@ -1,5 +1,5 @@
 import React from 'react';
-import { RuntimeAnswer, AssessmentContent, AssessmentAnswers, QuestionRuntimeProps } from '@youssefalmia/edpire-runtime';
+import { RuntimeAnswer, QuestionRuntimeProps, AssessmentContent, AssessmentAnswers } from '@youssefalmia/edpire-runtime';
 export { RuntimeAnswer } from '@youssefalmia/edpire-runtime';
 import * as react_jsx_runtime from 'react/jsx-runtime';
 import { RichContent } from '@youssefalmia/edpire-schema/authoring';
@@ -52,32 +52,6 @@ interface EdpireQuestionProps {
 }
 declare const EdpireQuestion: React.NamedExoticComponent<EdpireQuestionProps>;
 
-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 polished Assessment Shell.
  *
@@ -152,6 +126,208 @@ interface SubmitResult {
     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 EdpireAssessmentPlayerProps {
+    /**
+     * URL of YOUR server endpoint that returns `{ token }`.
+     *
+     * The component POSTs `{ assessmentId, ...tokenBody }` here and uses the
+     * returned `token` to mount the player. Your endpoint should resolve the
+     * learner from your session — never from the request body.
+     *
+     * Pair with `createEdpireTokenHandler()` from `@edpire/sdk/client` to build
+     * the endpoint in one line.
+     *
+     * @example "/api/edpire/token"
+     */
+    tokenEndpoint: string;
+    /** Assessment UUID to embed. Sent to `tokenEndpoint` in the POST body. */
+    assessmentId: string;
+    /**
+     * Extra body fields merged into the POST to `tokenEndpoint`.
+     * Useful for passing context your server needs beyond `assessmentId`
+     * (e.g. a course ID for allow-list validation).
+     */
+    tokenBody?: Record<string, unknown>;
+    /** Base URL of the Edpire instance. Defaults to `"https://edpire.com"`. */
+    baseUrl?: string;
+    /** UI language. Defaults to `"en"`. RTL layout is applied automatically for `"ar"`. */
+    locale?: ShellLocale;
+    /** Branding overrides. Org branding loads from Edpire automatically; pass this to override (white-labelling). */
+    branding?: TakeBranding;
+    /**
+     * When set, the post-submit "View Full Report" button redirects here with
+     * `?submission_id=...&score=...&max_score=...` appended. Omit to hide the button.
+     */
+    returnUrl?: string;
+    /** Custom label for the post-submit report/redirect button. */
+    reportLabel?: string;
+    /** Called when the learner clicks Back (shown only before submission). */
+    onBack?: () => void;
+    /** Custom label for the back button. */
+    backLabel?: string;
+    /** Customise the grading overlay (spinner theme, animation, colors). */
+    overlayConfig?: OverlayConfig;
+    /**
+     * Media upload/recording handler.
+     *
+     * **Required** if the assessment contains OpenResponse questions with
+     * file-upload or audio/video recording modes. Without it those questions
+     * will not function correctly.
+     *
+     * @example
+     * ```typescript
+     * mediaHandler: {
+     *   upload: async (file, { onProgress }) => {
+     *     const form = new FormData()
+     *     form.append("file", file)
+     *     const res = await fetch("/api/upload", { method: "POST", body: form })
+     *     const { url } = await res.json()
+     *     return { url }
+     *   },
+     * }
+     * ```
+     */
+    mediaHandler?: QuestionRuntimeProps["mediaHandler"];
+    /** Called when the learner successfully submits the assessment. */
+    onComplete?: (result: EmbedResult) => void;
+    /**
+     * Called when a non-recoverable error occurs (token fetch failure, invalid
+     * token, origin not allowed, etc.).
+     */
+    onError?: (error: EmbedError) => void;
+    /**
+     * CSS class name for the container `<div>`. Use this to control the player size.
+     *
+     * The player fills its container — you own the outer dimensions.
+     *
+     * @example "h-screen"          // full viewport height
+     * @example "h-[600px] w-full"  // fixed height
+     */
+    className?: string;
+    /**
+     * Inline style for the container `<div>`.
+     *
+     * When `className` is not set, defaults to `{ width: "100%", height: "100%" }`.
+     * Provide this (or `className`) to size the player — a zero-height container
+     * will collapse the player.
+     */
+    style?: React.CSSProperties;
+}
+/**
+ * Drop-in React component for the Edpire Embedded Player.
+ *
+ * Handles token fetching from your server, player mounting/unmounting, and
+ * React StrictMode double-invoke cleanup — the plumbing you'd otherwise write
+ * by hand with `useRef` + `useEffect`.
+ *
+ * The player fills its container: size it via `className` or `style`.
+ *
+ * @example
+ * ```tsx
+ * import { EdpireAssessmentPlayer } from "@edpire/sdk/react"
+ *
+ * function AssessmentPage({ assessmentId }: { assessmentId: string }) {
+ *   return (
+ *     <EdpireAssessmentPlayer
+ *       tokenEndpoint="/api/edpire/token"
+ *       assessmentId={assessmentId}
+ *       onComplete={(r) => console.log("Score:", r.score, "/", r.max_score)}
+ *       onError={(e) => console.error(e.code, e.message)}
+ *       className="h-screen"
+ *     />
+ *   )
+ * }
+ * ```
+ */
+declare function EdpireAssessmentPlayer({ tokenEndpoint, assessmentId, tokenBody, className, style, onComplete, onError, ...mountOptions }: EdpireAssessmentPlayerProps): react_jsx_runtime.JSX.Element;
+
 interface AssessmentShellProps {
     assessment: AssessmentContent;
     meta: {
@@ -197,4 +373,4 @@ interface AssessmentShellProps {
 }
 declare function AssessmentShell({ assessment, meta, locale, branding, timeLimitMinutes, startedAt, onSubmit, onViewReport, reportLabel, onBack, backLabel, allowReset, onReset, overlayConfig, contained, onClose, mediaHandler, fallbackLogoUrl, }: AssessmentShellProps): react_jsx_runtime.JSX.Element;
 
-export { AssessmentShell, type AssessmentShellProps, EdpireQuestion, type EdpireQuestionProps, type ExerciseFeedbackData, type NodeDetail, type NodeFeedback, type OverlayConfig, type QuestionFeedback, type ShellLocale, type SpinnerTheme, type SubmitResult, type TakeBranding };
+export { AssessmentShell, type AssessmentShellProps, EdpireAssessmentPlayer, type EdpireAssessmentPlayerProps, EdpireQuestion, type EdpireQuestionProps, type ExerciseFeedbackData, type NodeDetail, type NodeFeedback, type OverlayConfig, type QuestionFeedback, type ShellLocale, type SpinnerTheme, type SubmitResult, type TakeBranding };