Embedded Player

Your server  ──mintEmbedToken()──▶  Edpire        (API key stays server-side)
     │
     ▼  token
Your browser ──EdpireAssessment.mount({ token })──▶  player renders in your <div>
     │
     ▼  onComplete(result)
Your app handles the score

// app/api/edpire/token/route.ts  (Next.js App Router)
import { createEdpireTokenHandler } from "@edpire/sdk/client"

export const POST = createEdpireTokenHandler({
  apiKey: process.env.EDPIRE_API_KEY!,  // server-side only — never NEXT_PUBLIC_
  resolveLearner: async (req) => {
    // Read the learner from YOUR session — never from the request body.
    const session = await auth.api.getSession({ headers: req.headers })
    return session?.user.id ?? null   // null → 401 Unauthorized
  },
})

import { EdpireAssessmentPlayer } from "@edpire/sdk/react"

<EdpireAssessmentPlayer
  tokenEndpoint="/api/edpire/token"
  assessmentId="your-assessment-uuid"
  onComplete={(r) => console.log("Score:", r.score, "/", r.max_score)}
  onError={(e) => console.error(e.code, e.message)}
  style={{ width: "100%", height: "100vh" }}
/>

import { EdpireAssessment } from "@edpire/sdk"

const { token } = await fetch("/api/edpire/token", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ assessmentId: "your-uuid" }),
}).then((r) => r.json())

const embed = EdpireAssessment.mount({
  token,
  container: "#assessment-root",    // CSS selector or HTMLElement
  onComplete: (result) => {
    console.log(`Score: ${result.score}/${result.max_score} (${result.percentage}%)`)
    console.log(`Passed: ${result.passed}`)
  },
  onError: (err) => console.error(err.code, err.message),
})

// When you're done (e.g. closing a modal):
embed.unmount()

/* Minimal example — full viewport */
#assessment-root {
  width: 100%;
  height: 100vh;
}

/* React — use className or style prop */
<EdpireAssessmentPlayer style={{ width: "100%", height: "100vh" }} ... />

# .env
EDPIRE_API_KEY=edp_live_...   # server-side only — never NEXT_PUBLIC_ or VITE_

EdpireAssessment.mount({
  token,
  container: "#root",
  mediaHandler: {
    /**
     * Called when the learner selects a file (image, audio, video, document).
     * Upload it to your storage and return the permanent URL.
     */
    upload: async (file, { onProgress }) => {
      const form = new FormData()
      form.append("file", file)

      // Example: your own upload endpoint backed by S3, R2, etc.
      const xhr = new XMLHttpRequest()
      return new Promise((resolve, reject) => {
        xhr.upload.onprogress = (e) => onProgress?.(e.loaded / e.total)
        xhr.onload = () => {
          const { url } = JSON.parse(xhr.responseText) as { url: string }
          resolve({ url })
        }
        xhr.onerror = reject
        xhr.open("POST", "/api/upload")
        xhr.send(form)
      })
    },
  },
})

## Return value — `EmbedInstance`

```typescript
interface EmbedInstance {
  unmount: () => void
}

interface EmbedResult {
  submission_id: string
  score: number
  max_score: number
  percentage: number
  passed: boolean
  passing_score_percent: number
  attempt_number: number
  /** True when open-response nodes are still pending teacher review. */
  awaiting_manual_grading?: boolean

  /**
   * Per-question scores — use this for scorecards, gradebooks, or
   * recording results. Has scores but not the visual feedback state.
   */
  exercise_results: Array<{
    exercise_id: string
    total_score: number
    max_score: number
    question_results: Array<{
      question_id: string
      score: number
      correct: boolean
      points: number
    }>
  }>

  /**
   * Per-node visual feedback — use this to show learners what they got
   * right/wrong inline. Includes status, display_answer, and correctChoiceIds.
   * The player renders this automatically; access it if you're building a
   * custom results screen.
   */
  exercise_feedback: Array<{
    exercise_id: string
    questions: Array<{
      question_id: string
      node_results: Array<{
        node_id: string
        status: "correct" | "partial" | "incorrect" | "awaiting_review"
        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
}

<div id="root"></div>
<script src="https://cdn.jsdelivr.net/npm/@edpire/sdk@0.6.4/dist/umd/index.global.js"></script>
<script>
  EdpireSDK.EdpireAssessment.mount({ token: "…", container: "#root", onComplete: handleDone })
</script>