@edpire/sdk 0.5.0

package/LICENSE

@@ -0,0 +1,51 @@
+Edpire SDK License Agreement
+
+Copyright (c) 2026 Edpire (Youssef Almia). All rights reserved.
+
+This software, including its source code, compiled bundles, and accompanying
+files (the "Software"), is the proprietary property of Edpire. By downloading,
+installing, or using the Software you agree to the terms below.
+
+1. License grant.
+   Edpire grants you a non-exclusive, non-transferable, revocable license to
+   download, install, and use the Software for the sole purpose of integrating
+   your own application or service with the Edpire platform via Edpire's
+   official APIs and services.
+
+2. Restrictions.
+   Except as expressly permitted in Section 1, you may NOT:
+   (a) copy, redistribute, sublicense, sell, rent, or otherwise make the
+       Software (in source or compiled form) available to any third party as a
+       standalone product;
+   (b) modify, adapt, translate, or create derivative works of the Software,
+       except for configuration and integration code that calls the Software's
+       public interfaces;
+   (c) reverse engineer, decompile, or disassemble the Software, or use it or
+       any portion of it, to design, develop, or operate a product or service
+       that competes with the Edpire platform;
+   (d) remove, alter, or obscure any proprietary notices in the Software.
+
+   The presence of human-readable code in any distributed bundle does not grant
+   any right to reuse it beyond the license granted in Section 1.
+
+3. Ownership.
+   The Software is licensed, not sold. Edpire retains all right, title, and
+   interest in and to the Software, including all intellectual property rights.
+
+4. No warranty.
+   THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+   IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+   FITNESS FOR A PARTICULAR PURPOSE, AND NONINFRINGEMENT.
+
+5. Limitation of liability.
+   IN NO EVENT SHALL EDPIRE BE LIABLE FOR ANY CLAIM, DAMAGES, OR OTHER
+   LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT, OR OTHERWISE, ARISING
+   FROM, OUT OF, OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
+   DEALINGS IN THE SOFTWARE.
+
+6. Termination.
+   This license terminates automatically if you breach any of its terms. Upon
+   termination you must cease all use of the Software and destroy all copies in
+   your possession.
+
+For licensing inquiries beyond the scope of this grant, contact Edpire.

package/README.md

@@ -0,0 +1,443 @@
+# @edpire/sdk
+
+Embeddable assessment SDK for Edpire. Deliver, render, and grade assessments from your own application.
+
+> 📚 **Full documentation** lives in the Edpire docs site under [**SDK Reference**](https://docs.edpire.com/developer/sdk/overview) — complete option/prop/type tables for the Embedded Player, React components, Custom Flow, server client, and branding. This README is a condensed quick-start.
+
+---
+
+## Which approach fits you?
+
+| Approach | Learner stays on your page? | You build the UI? | Entry point |
+|---|---|---|---|
+| **[Hosted Redirect](#hosted-redirect)** | No | No | Share URL only |
+| **[Embedded Player](#embedded-player)** | Yes | No | `EdpireAssessment.mount()` |
+| **[Custom Flow](#custom-flow)** | Yes | Yes | `renderQuestion` + `flattenAssessment` |
+
+> **Server Client** (`EdpireClient`) is a backend utility used alongside any of the above — not a separate approach. [Jump to Server Client →](#server-client)
+
+---
+
+## Installation
+
+Published to the public npm registry — no auth token required.
+
+```bash
+npm install @edpire/sdk
+# or
+pnpm add @edpire/sdk
+```
+
+> **License:** the package is free to install but carries a proprietary, integrate-with-Edpire-only license (see `LICENSE`). It is safe to make public because the bundle is only the question renderer — answer keys, grading, and API keys never ship in it; they stay on the server.
+
+---
+
+## Hosted Redirect
+
+The simplest integration — no SDK required on the frontend. Redirect learners to Edpire's hosted assessment UI. After completion, Edpire redirects back to your `return_url` with results.
+
+```
+https://{your-slug}.edpire.com/take/{shareCode}?learner_ref={userId}&return_url={yourUrl}
+```
+
+| Parameter | Required | Description |
+|-----------|----------|-------------|
+| `shareCode` | Yes | Assessment share code from the dashboard |
+| `learner_ref` | Recommended | Your stable internal user ID |
+| `return_url` | Recommended | Where to send the learner after completion |
+
+Edpire appends `?submission_id=...&score=...&max_score=...` to the return URL.
+
+**When to use:** Fast adoption, no custom UI needed, comfortable with a browser redirect.
+
+---
+
+## Embedded Player
+
+Mount Edpire's full assessment player inline inside your page. The SDK fetches the assessment, handles all interactions, grades the submission, and shows per-question feedback — all automatically. The learner never leaves your app.
+
+**Server (Node.js / API route):**
+
+```typescript
+import { EdpireClient } from "@edpire/sdk/client"
+
+const client = new EdpireClient({ apiKey: process.env.EDPIRE_API_KEY! })
+
+// Mint a short-lived single-use token for this learner + assessment
+const { token } = await client.mintEmbedToken(assessmentId, userId)
+// Pass `token` to the browser (e.g. via server-rendered props or an API response)
+```
+
+**Browser:**
+
+```typescript
+import { EdpireAssessment } from "@edpire/sdk"
+
+const embed = EdpireAssessment.mount({
+  token,                           // from your server
+  container: "#assessment-root",   // CSS selector or HTMLElement
+  onComplete: (result) => {
+    console.log(`Score: ${result.score}/${result.max_score}`)
+    console.log(`Passed: ${result.passed}`)
+  },
+  onError: (err) => console.error(err.message),
+})
+
+// Later, when done:
+embed.unmount()
+```
+
+**CDN (no bundler):**
+
+```html
+<script src="https://cdn.jsdelivr.net/npm/@edpire/sdk@0.5.0/dist/umd/index.global.js"></script>
+<script>
+  EdpireSDK.EdpireAssessment.mount({ token, container: "#root", onComplete: handleDone })
+</script>
+```
+
+> The UMD build is served straight from npm by [jsDelivr](https://www.jsdelivr.com/) (and [unpkg](https://unpkg.com/)) — no CDN to run yourself. Pin a version for production; `@latest` works for prototyping.
+
+**When to use:** You want the full assessment experience inside your page with a single function call. Zero UI code required.
+
+---
+
+## Custom Flow
+
+Build your own question-by-question UX — Duolingo-style flows, flashcard drills, practice modes, custom navigation. The SDK handles question rendering and answer collection; you own everything else.
+
+**How it works:**
+1. Your server fetches the assessment (keeping your API key server-side)
+2. `flattenAssessment()` converts it into a flat array of question steps
+3. `renderQuestion()` (or `<EdpireQuestion>` in React) renders each step into a container you control
+4. Your server grades each answer via the `/check` endpoint
+5. After all questions, your server submits the full attempt
+
+**Server — fetch the assessment:**
+
+```typescript
+// GET /api/edpire/assessment/[id]/route.ts
+import { EdpireClient } from "@edpire/sdk/client"
+
+const client = new EdpireClient({ apiKey: process.env.EDPIRE_API_KEY! })
+const assessment = await client.getAssessment(assessmentId)
+return NextResponse.json({ data: assessment })
+```
+
+**Browser — flatten and render:**
+
+```tsx
+// React
+import { flattenAssessment } from "@edpire/sdk"
+import { EdpireQuestion } from "@edpire/sdk/react"
+import type { RuntimeAnswer } from "@edpire/sdk"
+
+const steps = flattenAssessment(assessment)
+// steps[i] = { exerciseId, questionId, content, points, sequenceNumber, index }
+
+const [currentIndex, setCurrentIndex] = useState(0)
+const [answers, setAnswers] = useState<RuntimeAnswer[]>([])
+const [feedback, setFeedback] = useState(null)
+const step = steps[currentIndex]
+
+<EdpireQuestion
+  content={step.content}
+  onAnswersChange={setAnswers}
+  feedback={feedback}   // null = no feedback shown; pass result of /check to show it
+  dir="ltr"             // or "rtl" for Arabic
+/>
+```
+
+```typescript
+// Vanilla JS
+import { flattenAssessment, renderQuestion } from "@edpire/sdk"
+
+const steps = flattenAssessment(assessment)
+const step = steps[currentIndex]
+
+const question = renderQuestion({
+  container: document.getElementById("question-root"),
+  content: step.content,
+  onAnswersChange: (answers) => { /* store answers */ },
+})
+
+// Later, update feedback:
+question.setFeedback(feedbackFromCheckEndpoint)
+
+// Move to next question:
+question.setContent(steps[nextIndex].content)
+```
+
+**Server — grade each question via your proxy:**
+
+```typescript
+// POST /api/edpire/check/[id]/route.ts  (recommended — type-safe, handles URL construction)
+import { EdpireClient } from "@edpire/sdk/client"
+
+const client = new EdpireClient({ apiKey: process.env.EDPIRE_API_KEY! })
+
+export async function POST(req: Request, { params }: { params: Promise<{ id: string }> }) {
+  const { id } = await params
+  const body = await req.json()
+  // Always set include_correct_answers server-side — never trust the client to send it
+  const result = await client.checkQuestion(id, { ...body, include_correct_answers: true })
+  return Response.json(result)  // result: CheckResult = { correct, score, max_score, feedback }
+}
+```
+
+<details>
+<summary>Alternative — raw fetch without EdpireClient</summary>
+
+```typescript
+// Note: assessmentId goes in the URL path, not the request body
+const result = await fetch(`https://edpire.com/api/v1/assessments/${assessmentId}/check`, {
+  method: "POST",
+  headers: {
+    Authorization: `Bearer ${process.env.EDPIRE_API_KEY}`,
+    "Content-Type": "application/json",
+  },
+  body: JSON.stringify({
+    exercise_id: exerciseId,
+    question_id: questionId,
+    answers,
+    learner_ref: userId,
+    session_id: sessionId,
+    include_correct_answers: true,
+  }),
+}).then((r) => r.json())
+// Response envelope: { data: CheckResult, error: null, meta: null }
+```
+
+</details>
+
+**Server — submit the full attempt when done:**
+
+```typescript
+import { EdpireClient } from "@edpire/sdk/client"
+import type { StoredAnswer } from "@edpire/sdk"
+
+const stored: StoredAnswer[] = []
+// push { exerciseId, questionId, answers } for each step as the learner answers
+
+const client = new EdpireClient({ apiKey: process.env.EDPIRE_API_KEY! })
+const result = await client.submit(assessmentId, {
+  learner_ref: userId,
+  answers: stored,   // StoredAnswer[] — the client handles nesting automatically
+})
+console.log(`Final score: ${result.score}/${result.max_score}`)
+```
+
+<details>
+<summary>Rate limiting on /check</summary>
+
+Each `(session_id, question_id)` pair is limited to 3 checks per hour (configurable per org).
+
+**Always pass a `session_id`** — generate a UUID once at the start of each attempt:
+```typescript
+const sessionId = crypto.randomUUID()  // generate once per attempt, not per question
+```
+If omitted, rate limiting falls back to `learner_ref`, which accumulates across all of a learner's attempts and can cause unexpected 429s on repeat attempts.
+
+</details>
+
+**Required API key scopes:** `read:assessments` (for fetching and checking) + `write:submissions` (for the final submit).
+
+**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.
+
+---
+
+## Server Client
+
+`EdpireClient` is a backend-only utility for calling the Edpire REST API from your server. It is not a rendering pattern — it is used alongside Embedded Player and Custom Flow.
+
+```typescript
+import { EdpireClient } from "@edpire/sdk/client"
+
+const client = new EdpireClient({
+  apiKey: process.env.EDPIRE_API_KEY!,
+  baseUrl: "https://edpire.com",  // optional, defaults to edpire.com
+})
+```
+
+**Common operations:**
+
+```typescript
+// List published assessments
+const { items } = await client.getAssessments({ status: "published" })
+
+// Fetch a single assessment with full content
+const assessment = await client.getAssessment(assessmentId)
+
+// Mint an embed token (for Embedded Player)
+const { token } = await client.mintEmbedToken(assessmentId, learnerRef)
+
+// Submit a full attempt (for Custom Flow)
+const result = await client.submit(assessmentId, { learner_ref: userId, answers: stored })
+
+// Grade a single question without recording (for Custom Flow /check)
+const check = await client.checkQuestion(assessmentId, {
+  exercise_id, question_id, answers, learner_ref, session_id,
+  include_correct_answers: true,
+})
+
+// Register a webhook
+const webhook = await client.registerWebhook("https://yourapp.com/webhooks/edpire", [
+  "submission.graded",
+])
+// Store webhook.secret securely — shown only once
+```
+
+---
+
+## Mobile & WebView integration
+
+Flutter, React Native, and native iOS/Android apps cannot import this npm package directly.
+The integration uses two parts:
+
+1. **Your backend** mints an embed token via `client.mintEmbedToken()` (the API key stays server-side).
+2. **A WebView** in your mobile app loads a minimal HTML page that calls the CDN UMD build with the token.
+
+> The UMD build is served from npm via [jsDelivr](https://www.jsdelivr.com/) — no CDN to host yourself.
+
+**Universal WebView HTML template:**
+
+```html
+<!DOCTYPE html>
+<html>
+<head>
+  <meta name="viewport" content="width=device-width, initial-scale=1" />
+  <style>* { margin: 0; padding: 0; box-sizing: border-box; } #root { min-height: 100vh; }</style>
+</head>
+<body>
+  <div id="root"></div>
+  <script src="https://cdn.jsdelivr.net/npm/@edpire/sdk@0.5.0/dist/umd/index.global.js"></script>
+  <script>
+    EdpireSDK.EdpireAssessment.mount({
+      token: "{{EMBED_TOKEN}}",   // replace server-side before loading
+      container: "#root",
+      onComplete: function(r) {
+        if (window.ReactNativeWebView)
+          window.ReactNativeWebView.postMessage(JSON.stringify({ type: "complete", result: r }))
+        if (window.flutter_inappwebview)
+          window.flutter_inappwebview.callHandler("onComplete", r)
+      },
+      onError: function(e) {
+        if (window.ReactNativeWebView)
+          window.ReactNativeWebView.postMessage(JSON.stringify({ type: "error", error: e }))
+        if (window.flutter_inappwebview)
+          window.flutter_inappwebview.callHandler("onError", e)
+      }
+    })
+  </script>
+</body>
+</html>
+```
+
+> **Ionic / Capacitor** apps run in a WebView — you can use the full npm SDK directly. No HTML template needed.
+
+For React Native, Flutter, and native iOS/Android code examples, see the [Mobile Integration guide](https://docs.edpire.com/developer/mobile).
+
+---
+
+## CSS
+
+**Embedded Player** (`EdpireAssessment.mount()`) — all CSS is injected automatically. No imports needed.
+
+**Custom Flow** (`EdpireQuestion` / `renderQuestion`) — styles are bundled into the SDK's JavaScript and injected when the component first renders. In most setups this is also automatic. If styles appear missing (e.g. in a sandboxed iframe or a strict CSP environment that blocks inline styles), import the utility stylesheet explicitly:
+
+```typescript
+import "@edpire/sdk/styles/runtime-utilities.css"
+```
+
+---
+
+## TypeScript types
+
+All commonly needed types are available from the main entry:
+
+```typescript
+import type {
+  // Answer types
+  RuntimeAnswer,
+  ChoiceSetAnswer,
+  BlankAnswer,
+  TypedBlankAnswer,
+  BlankChoiceAnswer,
+  MatchingSetAnswer,
+  AiAnswer,
+  OpenResponseAnswer,
+  MathResponseAnswer,
+
+  // Custom Flow helpers
+  StoredAnswer,    // { exerciseId, questionId, answers: RuntimeAnswer[] }
+  FlatStep,        // one step from flattenAssessment()
+
+  // Embedded Player
+  MountOptions,
+  EmbedInstance,
+  EmbedResult,
+  EmbedError,
+} from "@edpire/sdk"
+```
+
+Types specific to the Server Client come from `@edpire/sdk/client`:
+
+```typescript
+import type { Assessment, SubmitResult, CheckResult, EdpireClientOptions } from "@edpire/sdk/client"
+```
+
+---
+
+## Webhooks
+
+```typescript
+const webhook = await client.registerWebhook("https://yourapp.com/api/webhooks/edpire", [
+  "submission.graded",
+  "assessment.published",
+])
+// Store webhook.secret securely — it is only shown once.
+```
+
+**Verify incoming signatures:**
+
+```typescript
+import { createHmac, timingSafeEqual } from "crypto"
+
+export async function POST(req: Request) {
+  const rawBody = await req.text()
+  const signature = req.headers.get("x-edpire-signature") ?? ""
+
+  const expected = "sha256=" + createHmac("sha256", process.env.EDPIRE_WEBHOOK_SECRET!)
+    .update(rawBody)
+    .digest("hex")
+
+  if (!timingSafeEqual(Buffer.from(signature), Buffer.from(expected))) {
+    return new Response("Unauthorized", { status: 401 })
+  }
+
+  const event = JSON.parse(rawBody)
+  // event.event, event.submission_id, event.score, event.passed, ...
+}
+```
+
+**Available events:** `submission.graded`, `submission.pending_review`, `assessment.published`, `assessment.archived`
+
+---
+
+## Error handling
+
+`EdpireClient` throws `EdpireError` on non-2xx responses:
+
+```typescript
+import { EdpireError } from "@edpire/sdk/client"
+
+try {
+  await client.submit(assessmentId, options)
+} catch (err) {
+  if (err instanceof EdpireError) {
+    console.error(err.status, err.message)
+  }
+}
+```
+
+Common status codes: `400` bad request · `401` invalid API key · `404` not found · `409` max attempts reached · `422` grading failed · `429` rate limit exceeded