@edpire/sdk 0.6.0 → 0.6.2

package/bin/create.js

@@ -0,0 +1,61 @@
+#!/usr/bin/env node
+'use strict'
+
+const { cpSync, existsSync } = require('node:fs')
+const { resolve } = require('node:path')
+
+const TEMPLATES = ['nextjs', 'vite-express']
+const [, , template, dest] = process.argv
+
+function usage() {
+  console.error('Usage: create-edpire-app <template> <directory>')
+  console.error()
+  console.error('Templates:')
+  TEMPLATES.forEach((t) => console.error(`  ${t}`))
+  console.error()
+  console.error('Example:')
+  console.error('  npx --package=@edpire/sdk create-edpire-app nextjs ./my-app')
+}
+
+if (!template || !TEMPLATES.includes(template)) {
+  console.error(template ? `Unknown template: "${template}"` : 'Template required.')
+  console.error()
+  usage()
+  process.exit(1)
+}
+
+if (!dest) {
+  console.error('Destination directory required.')
+  console.error()
+  usage()
+  process.exit(1)
+}
+
+const src = resolve(__dirname, '..', 'examples', template)
+
+if (!existsSync(src)) {
+  console.error(`Template source not found: ${src}`)
+  console.error('Try reinstalling @edpire/sdk.')
+  process.exit(1)
+}
+
+if (existsSync(dest)) {
+  console.error(`Directory already exists: "${dest}"`)
+  console.error('Choose a different destination or remove the existing directory.')
+  process.exit(1)
+}
+
+try {
+  cpSync(src, dest, { recursive: true })
+} catch (err) {
+  console.error(`Failed to copy template: ${err.message}`)
+  process.exit(1)
+}
+
+console.log(`✓ Created "${dest}" from the ${template} template.`)
+console.log()
+console.log('Next steps:')
+console.log(`  cd ${dest}`)
+console.log('  cp .env.example .env    # fill in EDPIRE_API_KEY')
+console.log('  npm install')
+console.log('  npm run dev')

package/examples/nextjs/.env.example

@@ -0,0 +1,6 @@
+# Your Edpire API key — get one at https://edpire.com/org/integrations
+# NEVER prefix this with VITE_ or NEXT_PUBLIC_ — it must stay server-side only.
+EDPIRE_API_KEY=edp_live_your_key_here
+
+# The assessment UUID to embed (find it in the Edpire dashboard)
+NEXT_PUBLIC_ASSESSMENT_ID=your-assessment-uuid-here

package/examples/nextjs/README.md

@@ -0,0 +1,66 @@
+# Edpire SDK — Next.js example
+
+Embeds an Edpire assessment player inside a Next.js App Router page using:
+- `createEdpireTokenHandler()` for the server token endpoint (one call, one file)
+- `<EdpireAssessmentPlayer>` for the browser component (no useRef/useEffect needed)
+
+```
+Your browser  → POST /api/edpire/token
+Next.js server → mintEmbedToken(assessmentId, session.userId)  ← API key never leaves the server
+Browser        → EdpireAssessmentPlayer renders the full assessment UI
+```
+
+## Quickstart
+
+```bash
+cp .env.example .env.local
+# Fill in EDPIRE_API_KEY (from edpire.com/org/integrations) and NEXT_PUBLIC_ASSESSMENT_ID
+npm install
+npm run dev
+```
+
+Open http://localhost:3000 — the player loads.
+
+## How the token endpoint works
+
+`app/api/edpire/token/route.ts` exports `createEdpireTokenHandler()` directly as the `POST` handler. In production you replace the cookie-reading `resolveLearner` stub with your real auth session:
+
+```typescript
+// With NextAuth
+resolveLearner: async (req) => {
+  const session = await getServerSession(authOptions)
+  return session?.user.id ?? null
+}
+
+// With Better Auth
+resolveLearner: async (req) => {
+  const session = await auth.api.getSession({ headers: req.headers })
+  return session?.user.id ?? null
+}
+```
+
+Returning `null` rejects with 401 — the player never receives a token.
+
+## Allowed Origins
+
+If you see a blank player (no error, no content), your app's origin is not in Edpire's allow-list:
+
+1. Go to **edpire.com → Settings → Integrations → Allowed Origins**
+2. Add `http://localhost:3000` for dev, your production domain for prod
+3. Reload — the player should appear
+
+See [SDK Troubleshooting](https://docs.edpire.com/developer/sdk/troubleshooting) for more.
+
+## Production
+
+This example works in both `next dev` and `next build && next start`. The `/api/edpire/token` route is a real server-side endpoint in both modes — not a dev-only workaround.
+
+## Project structure
+
+```
+app/
+  api/edpire/token/route.ts  ← server: mints embed tokens
+  layout.tsx
+  page.tsx                   ← client: renders <EdpireAssessmentPlayer>
+.env.example
+```

package/examples/nextjs/app/api/edpire/token/route.ts

@@ -0,0 +1,38 @@
+/**
+ * Token-minting endpoint for the Edpire Embedded Player.
+ *
+ * The browser POSTs { assessmentId } here; this handler resolves the learner
+ * from the session and returns a short-lived, single-use embed token.
+ *
+ * Powered by createEdpireTokenHandler() — one call handles auth checking,
+ * token minting, and error mapping.
+ */
+import { createEdpireTokenHandler } from "@edpire/sdk/client"
+
+export const POST = createEdpireTokenHandler({
+  apiKey: process.env.EDPIRE_API_KEY!,
+
+  /**
+   * Resolve the learner ID from YOUR auth system.
+   *
+   * This example reads a `userId` cookie set by a login flow.
+   * In a real app replace this with your session/auth library:
+   *
+   * @example Next.js + NextAuth
+   *   const session = await getServerSession(req, res, authOptions)
+   *   return session?.user?.id ?? null
+   *
+   * @example Next.js + Better Auth
+   *   const session = await auth.api.getSession({ headers: req.headers })
+   *   return session?.user.id ?? null
+   *
+   * Returning null → 401 Unauthorized (no token minted).
+   * Never read the learner ID from the request body — that's an open relay.
+   */
+  resolveLearner: (req) => {
+    // Demo: read userId from a signed cookie. Replace with your auth session.
+    const cookie = req.headers.get("cookie") ?? ""
+    const match = /(?:^|;\s*)userId=([^;]+)/.exec(cookie)
+    return match ? decodeURIComponent(match[1]) : null
+  },
+})

package/examples/nextjs/app/globals.css

@@ -0,0 +1,9 @@
+/* Reset body margin so the player fills the viewport without gaps. */
+* {
+  box-sizing: border-box;
+}
+
+body {
+  margin: 0;
+  padding: 0;
+}

package/examples/nextjs/app/layout.tsx

@@ -0,0 +1,13 @@
+import type { Metadata } from "next"
+
+export const metadata: Metadata = {
+  title: "Edpire SDK — Next.js example",
+}
+
+export default function RootLayout({ children }: { children: React.ReactNode }) {
+  return (
+    <html lang="en">
+      <body style={{ margin: 0 }}>{children}</body>
+    </html>
+  )
+}

package/examples/nextjs/app/page.tsx

@@ -0,0 +1,51 @@
+"use client"
+
+/**
+ * Example page: embed an Edpire assessment player.
+ *
+ * How it works:
+ * 1. EdpireAssessmentPlayer POSTs { assessmentId } to /api/edpire/token.
+ * 2. The route handler resolves the learner from the session, mints a token,
+ *    and returns { token }.
+ * 3. The player fetches the assessment content from Edpire using the token,
+ *    renders the full UI, and calls onComplete when the learner submits.
+ *
+ * You never see the API key in the browser.
+ */
+import { EdpireAssessmentPlayer } from "@edpire/sdk/react"
+
+const ASSESSMENT_ID = process.env.NEXT_PUBLIC_ASSESSMENT_ID
+
+export default function Page() {
+  if (!ASSESSMENT_ID) {
+    return (
+      <div style={{ padding: 32, fontFamily: "sans-serif" }}>
+        <strong>Set NEXT_PUBLIC_ASSESSMENT_ID in .env.local</strong>
+        <p>Copy .env.example → .env.local and fill in your assessment ID.</p>
+      </div>
+    )
+  }
+
+  return (
+    <EdpireAssessmentPlayer
+      tokenEndpoint="/api/edpire/token"
+      assessmentId={ASSESSMENT_ID}
+      onComplete={(result) => {
+        console.log("Assessment complete!", {
+          score: result.score,
+          max: result.max_score,
+          passed: result.passed,
+        })
+        // TODO: redirect to results page, update progress, etc.
+      }}
+      onError={(err) => {
+        console.error("Embed error:", err.code, err.message)
+        // err.code is one of: TOKEN_INVALID | TOKEN_EXPIRED | TOKEN_USED |
+        //   ORIGIN_NOT_ALLOWED | ASSESSMENT_NOT_FOUND | MAX_ATTEMPTS_REACHED |
+        //   NETWORK_ERROR | UNKNOWN
+      }}
+      // The player fills its container. style/className controls the height.
+      style={{ width: "100%", height: "100vh" }}
+    />
+  )
+}

package/examples/nextjs/next.config.ts

@@ -0,0 +1,8 @@
+import type { NextConfig } from "next"
+
+const nextConfig: NextConfig = {
+  // No special config needed for @edpire/sdk.
+  // The SDK is a standard ESM package — Next.js resolves it from node_modules.
+}
+
+export default nextConfig

package/examples/nextjs/package.json

@@ -0,0 +1,22 @@
+{
+  "name": "edpire-sdk-example-nextjs",
+  "version": "0.1.0",
+  "private": true,
+  "scripts": {
+    "dev": "next dev",
+    "build": "next build",
+    "start": "next start"
+  },
+  "dependencies": {
+    "@edpire/sdk": "^0.6.0",
+    "next": "^15.0.0",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "@types/react": "^19.0.0",
+    "@types/react-dom": "^19.0.0",
+    "typescript": "^5.0.0"
+  }
+}

package/examples/nextjs/tsconfig.json

@@ -0,0 +1,20 @@
+{
+  "compilerOptions": {
+    "target": "ES2017",
+    "lib": ["dom", "dom.iterable", "esnext"],
+    "allowJs": true,
+    "skipLibCheck": true,
+    "strict": true,
+    "noEmit": true,
+    "esModuleInterop": true,
+    "module": "esnext",
+    "moduleResolution": "bundler",
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "jsx": "preserve",
+    "incremental": true,
+    "plugins": [{ "name": "next" }]
+  },
+  "include": ["next-env.d.ts", "**/*.ts", "**/*.tsx", ".next/types/**/*.ts"],
+  "exclude": ["node_modules"]
+}

package/examples/vite-express/.env.example

@@ -0,0 +1,10 @@
+# Your Edpire API key — get one at https://edpire.com/org/integrations
+# NEVER prefix with VITE_ — that would expose the key in the browser bundle.
+EDPIRE_API_KEY=edp_live_your_key_here
+
+# The assessment UUID to embed (find it in the Edpire dashboard).
+# VITE_ prefix is safe here because this is a public ID, not a secret.
+VITE_ASSESSMENT_ID=your-assessment-uuid-here
+
+# Port for the Express server
+PORT=3001

package/examples/vite-express/README.md

@@ -0,0 +1,69 @@
+# Edpire SDK — Vite + Express example
+
+Embeds an Edpire assessment player using:
+- **Vite** for the React frontend (browser)
+- **Express** for the token endpoint (server) — works in both dev and production
+
+```
+Browser → POST /api/edpire/token (via Vite proxy in dev, Express directly in prod)
+Express → mintEmbedToken(assessmentId, session.userId)  ← API key never leaves the server
+Browser → <EdpireAssessmentPlayer> renders the full assessment UI
+```
+
+This is the production-correct version of the "put it in vite.config.ts" pattern. The Express server runs separately and survives `vite build` + `vite preview`.
+
+## Quickstart
+
+```bash
+cp .env.example .env
+# Fill in EDPIRE_API_KEY (from edpire.com/org/integrations) and VITE_ASSESSMENT_ID
+npm install
+npm run dev
+```
+
+Two processes start:
+- **Express** on port 3001 (token endpoint)
+- **Vite** on port 5173 (dev server, proxies /api → port 3001)
+
+Open http://localhost:5173 — the player loads.
+
+## How it differs from vite.config.ts middleware
+
+The test project at `edpire-sdk-test` put the token endpoint inside a Vite dev-server middleware. That's clean for local dev, but it only runs during `vite dev` — a production build has no `/api/edpire/token` and the embed silently fails.
+
+This example runs a real Express server that handles the token endpoint in both dev and production. The Vite proxy in dev routes `/api` requests to Express; in production, Express serves everything.
+
+## Env variables
+
+| Variable | Where used | VITE_ prefix? |
+|---|---|---|
+| `EDPIRE_API_KEY` | Express server | **No** — prefixing it would leak it to the browser bundle |
+| `VITE_ASSESSMENT_ID` | Vite/browser | **Yes** — this is a public ID, not a secret |
+
+This is the key insight: `VITE_` prefixed variables are compiled into the browser bundle. The API key must never be prefixed.
+
+## Allowed Origins
+
+If you see a blank player, your app's origin is not in Edpire's allow-list:
+
+1. Go to **edpire.com → Settings → Integrations → Allowed Origins**
+2. Add `http://localhost:5173` for dev, your production domain for prod
+3. Reload — the player should appear
+
+## Production
+
+```bash
+npm run build      # builds Vite frontend → dist/ + compiles server.ts
+NODE_ENV=production npm run preview   # starts Express serving dist/ + /api/edpire/token
+```
+
+## Project structure
+
+```
+server.ts           ← Express: /api/edpire/token endpoint + static files in prod
+vite.config.ts      ← Vite: dev server, proxies /api → Express
+src/
+  App.tsx           ← React: <EdpireAssessmentPlayer>
+  main.tsx
+.env.example
+```

package/examples/vite-express/index.html

@@ -0,0 +1,16 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>Edpire SDK — Vite + Express example</title>
+    <style>
+      * { box-sizing: border-box; }
+      body { margin: 0; }
+    </style>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/main.tsx"></script>
+  </body>
+</html>

package/examples/vite-express/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "edpire-sdk-example-vite-express",
+  "version": "0.1.0",
+  "private": true,
+  "scripts": {
+    "dev": "concurrently -k -n SERVER,VITE -c cyan,magenta \"tsx server.ts\" \"vite\"",
+    "build": "vite build && tsc -p tsconfig.server.json",
+    "preview": "tsx server.ts",
+    "type-check": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@edpire/sdk": "^0.6.0",
+    "cors": "^2.8.5",
+    "express": "^4.18.2",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0"
+  },
+  "devDependencies": {
+    "@types/cors": "^2.8.17",
+    "@types/express": "^4.17.21",
+    "@types/node": "^20.0.0",
+    "@types/react": "^19.0.0",
+    "@types/react-dom": "^19.0.0",
+    "@vitejs/plugin-react": "^4.0.0",
+    "concurrently": "^8.2.2",
+    "dotenv": "^16.3.1",
+    "tsx": "^4.7.0",
+    "typescript": "^5.0.0",
+    "vite": "^5.0.0"
+  }
+}

package/examples/vite-express/server.ts

@@ -0,0 +1,84 @@
+/**
+ * Express server — serves the token endpoint + static files in production.
+ *
+ * In development: Vite dev server runs separately (port 5173) and proxies
+ * /api requests here (port 3001). Run `npm run dev` to start both.
+ *
+ * In production: this server serves the Vite build output (dist/) and the
+ * /api/edpire/token endpoint. Run `npm run build` then `npm run preview`.
+ */
+import "dotenv/config"
+import express from "express"
+import cors from "cors"
+import path from "node:path"
+import { fileURLToPath } from "node:url"
+import { createEdpireTokenHandler, toNodeHandler } from "@edpire/sdk/client"
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url))
+const PORT = Number(process.env.PORT ?? 3001)
+const isDev = process.env.NODE_ENV !== "production"
+
+const app = express()
+
+// In dev, the Vite dev server (port 5173) calls this server for /api requests.
+// Allow cross-origin requests from localhost in development.
+if (isDev) {
+  app.use(cors({ origin: /localhost/ }))
+}
+
+// ── Token endpoint ─────────────────────────────────────────────────────────────
+//
+// The browser POSTs { assessmentId } here and receives { token }.
+// The learner ID is resolved from the server session — never from the body.
+//
+// toNodeHandler() adapts the Web-standard createEdpireTokenHandler() response
+// to Express's (req, res) signature.
+const edpireTokenHandler = toNodeHandler(
+  createEdpireTokenHandler({
+    apiKey: process.env.EDPIRE_API_KEY!,
+
+    /**
+     * Resolve the learner ID from YOUR session.
+     *
+     * This example reads a `userId` cookie set by your login flow.
+     * Replace with your real session middleware in production:
+     *
+     * @example express-session
+     *   resolveLearner: (req) => req.session?.userId ?? null
+     *
+     * @example JWT
+     *   resolveLearner: (req) => {
+     *     const { userId } = jwt.verify(req.cookies.token, JWT_SECRET)
+     *     return userId ?? null
+     *   }
+     *
+     * Returning null → 401 (no token minted).
+     */
+    resolveLearner: (req) => {
+      const cookie = req.headers.get("cookie") ?? ""
+      const match = /(?:^|;\s*)userId=([^;]+)/.exec(cookie)
+      return match ? decodeURIComponent(match[1]) : null
+    },
+  }),
+)
+
+app.post("/api/edpire/token", edpireTokenHandler)
+
+// ── Static files (production only) ────────────────────────────────────────────
+if (!isDev) {
+  const distPath = path.join(__dirname, "dist")
+  app.use(express.static(distPath))
+  // SPA fallback — send index.html for all non-API routes
+  app.get(/^(?!\/api).*$/, (_req, res) => {
+    res.sendFile(path.join(distPath, "index.html"))
+  })
+}
+
+app.listen(PORT, () => {
+  if (isDev) {
+    console.log(`[server] Token endpoint ready at http://localhost:${PORT}/api/edpire/token`)
+    console.log(`[server] Start Vite dev server with: npm run dev`)
+  } else {
+    console.log(`[server] Production server at http://localhost:${PORT}`)
+  }
+})

package/examples/vite-express/src/App.tsx

@@ -0,0 +1,56 @@
+/**
+ * Edpire SDK — Vite + Express example
+ *
+ * How it works:
+ * 1. App.tsx renders <EdpireAssessmentPlayer> which POSTs { assessmentId }
+ *    to /api/edpire/token (proxied to the Express server in dev).
+ * 2. The Express server (server.ts) resolves the learner from the session,
+ *    mints a token via EdpireClient, and returns { token }.
+ * 3. The player fetches assessment content from Edpire using the token and
+ *    renders the full UI.
+ *
+ * The secret EDPIRE_API_KEY never touches the browser.
+ */
+import { EdpireAssessmentPlayer } from "@edpire/sdk/react"
+
+// VITE_ASSESSMENT_ID is safe to expose in the browser (it's a public ID, not a secret).
+const ASSESSMENT_ID = import.meta.env.VITE_ASSESSMENT_ID as string | undefined
+
+export default function App() {
+  if (!ASSESSMENT_ID) {
+    return (
+      <div style={{ padding: 32, fontFamily: "sans-serif" }}>
+        <strong>Set VITE_ASSESSMENT_ID in .env</strong>
+        <p>Copy .env.example → .env and fill in your assessment ID.</p>
+        <p>
+          <em>Note: EDPIRE_API_KEY must NOT have the VITE_ prefix — that would leak it to the
+          browser. Only the assessment ID is prefixed.</em>
+        </p>
+      </div>
+    )
+  }
+
+  return (
+    <EdpireAssessmentPlayer
+      tokenEndpoint="/api/edpire/token"
+      assessmentId={ASSESSMENT_ID}
+      onComplete={(result) => {
+        console.log("Assessment complete!", {
+          score: result.score,
+          max: result.max_score,
+          passed: result.passed,
+        })
+        // TODO: redirect to results page, update progress, etc.
+      }}
+      onError={(err) => {
+        console.error("Embed error:", err.code, err.message)
+        // Common errors:
+        // ORIGIN_NOT_ALLOWED → add localhost to Allowed Origins in the dashboard
+        // TOKEN_INVALID      → check EDPIRE_API_KEY in .env
+        // ASSESSMENT_NOT_FOUND → check VITE_ASSESSMENT_ID in .env
+      }}
+      // The player fills its container. Set a height here or via CSS.
+      style={{ width: "100%", height: "100vh" }}
+    />
+  )
+}

package/examples/vite-express/src/main.tsx

@@ -0,0 +1,9 @@
+import React from "react"
+import { createRoot } from "react-dom/client"
+import App from "./App"
+
+createRoot(document.getElementById("root")!).render(
+  <React.StrictMode>
+    <App />
+  </React.StrictMode>,
+)

package/examples/vite-express/tsconfig.json

@@ -0,0 +1,17 @@
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "useDefineForClassFields": true,
+    "lib": ["ES2020", "DOM", "DOM.Iterable"],
+    "module": "ESNext",
+    "skipLibCheck": true,
+    "moduleResolution": "bundler",
+    "allowImportingTsExtensions": true,
+    "isolatedModules": true,
+    "moduleDetection": "force",
+    "noEmit": true,
+    "jsx": "react-jsx",
+    "strict": true
+  },
+  "include": ["src"]
+}

package/examples/vite-express/tsconfig.server.json

@@ -0,0 +1,12 @@
+{
+  "extends": "./tsconfig.json",
+  "compilerOptions": {
+    "noEmit": false,
+    "outDir": "dist-server",
+    "module": "ESNext",
+    "moduleResolution": "node",
+    "target": "node18",
+    "allowImportingTsExtensions": false
+  },
+  "include": ["server.ts"]
+}

package/examples/vite-express/vite.config.ts

@@ -0,0 +1,18 @@
+import { defineConfig } from "vite"
+import react from "@vitejs/plugin-react"
+
+export default defineConfig({
+  plugins: [react()],
+
+  server: {
+    port: 5173,
+    proxy: {
+      // In development, proxy /api requests to the Express server.
+      // This keeps the secret EDPIRE_API_KEY server-side (never in the browser bundle).
+      "/api": {
+        target: "http://localhost:3001",
+        changeOrigin: true,
+      },
+    },
+  },
+})

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@edpire/sdk",
-  "version": "0.6.0",
+  "version": "0.6.2",
   "description": "Embeddable JS SDK for Edpire assessments",
   "license": "SEE LICENSE IN LICENSE",
   "homepage": "https://docs.edpire.com/developer/sdk/overview",
@@ -38,9 +38,14 @@
     "./styles/runtime-utilities.css": "./src/styles/runtime-utilities.css",
     "./styles/shell.css": "./src/styles/shell.css"
   },
+  "bin": {
+    "create-edpire-app": "bin/create.js"
+  },
   "files": [
     "dist",
-    "src/styles"
+    "src/styles",
+    "examples",
+    "bin"
   ],
   "dependencies": {
     "@dnd-kit/core": "^6.3.1",

package/dist/client.d.mts

@@ -1,540 +0,0 @@
-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[];
-}
-
-/**
- * @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: [...] },
- * })
- * ```
- */
-
-declare class EdpireError extends Error {
-    /** HTTP status code from the API response. */
-    status: number;
-    constructor(status: number, message: string);
-}
-interface EdpireClientOptions {
-    /** Your Edpire API key (starts with `edp_live_`). Store server-side only. */
-    apiKey: string;
-    /** Base URL of the Edpire API. Defaults to `"https://edpire.com"`. */
-    baseUrl?: string;
-    /** Custom fetch implementation (for testing or edge runtimes). */
-    fetch?: typeof globalThis.fetch;
-}
-/** 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;
-}
-interface PaginatedResponse<T> {
-    items: T[];
-    total: number;
-    page: number;
-    limit: number;
-}
-interface SubmitOptions {
-    /** Your stable user ID for the learner. */
-    learner_ref: string;
-    /**
-     * Assessment answers. Accepts two formats:
-     *
-     * **Flat array (recommended for custom players):** Pass a `StoredAnswer[]`
-     * collected during the session — one entry per question. The client converts
-     * it to the nested format automatically using `buildSubmitPayload()`.
-     *
-     * ```typescript
-     * answers: stored  // StoredAnswer[] — exerciseId + questionId + RuntimeAnswer[]
-     * ```
-     *
-     * **Nested format (advanced):** The raw `exerciseAnswers` structure expected
-     * by the API. Use this if you're constructing the payload manually.
-     *
-     * ```typescript
-     * answers: { exerciseAnswers: [{ exerciseId, questionAnswers: [...] }] }
-     * ```
-     */
-    answers: StoredAnswer[] | {
-        exerciseAnswers: Array<{
-            exerciseId: string;
-            questionAnswers: Array<{
-                questionId: string;
-                answers: Array<Record<string, unknown>>;
-            }>;
-        }>;
-    };
-    /** Set to true to submit against draft assessments (for testing). */
-    allow_draft?: boolean;
-    /** Optional consumer-side metadata (not stored by Edpire). */
-    metadata?: Record<string, unknown>;
-}
-/** Result returned by `EdpireClient.submit()` after a full submission is graded. */
-interface GradeResult {
-    submission_id: string;
-    score: number;
-    max_score: number;
-    percentage: number;
-    passed: boolean;
-    passing_score_percent: number;
-    attempt_number: number;
-    exercise_results: Array<{
-        exercise_id: string;
-        total_score: number;
-        max_score: number;
-        question_results: Array<{
-            question_id: string;
-            score: number;
-            max_score: number;
-            correct: boolean;
-            points: number;
-            feedback: Record<string, unknown>;
-        }>;
-    }>;
-}
-interface CheckOptions {
-    /** Exercise ID containing the question. */
-    exercise_id: string;
-    /** Question ID to grade. */
-    question_id: string;
-    /** Learner's answers — pass the RuntimeAnswer[] array from EdpireQuestion's onAnswersChange directly. */
-    answers: RuntimeAnswer[];
-    /** Your stable user ID for rate limiting. */
-    learner_ref: string;
-    /**
-     * Session ID for rate limiting — generate once per attempt with crypto.randomUUID().
-     * If omitted, rate limiting falls back to learner_ref, which accumulates across
-     * all attempts by the same learner. Always pass a session_id in production.
-     */
-    session_id: string;
-    /**
-     * When true, the feedback includes correct-answer fields:
-     * - `correctChoiceIds` for choice/drag-drop questions
-     * - `correctPairings` for matching questions
-     * - `displayAnswer` for typed blank questions
-     *
-     * Use this in Duolingo-style flows to reveal the correct answer after the
-     * learner has committed their response. Rate limiting (3 checks per question
-     * per session) prevents brute-force abuse.
-     *
-     * Default: false — correct answers are never revealed.
-     */
-    include_correct_answers?: boolean;
-}
-interface CheckResult {
-    correct: boolean;
-    score: number;
-    max_score: number;
-    feedback: Record<string, unknown>;
-}
-interface Submission {
-    id: string;
-    assessment_id: string;
-    learner_id: string | null;
-    learner_ref: string | null;
-    status: string;
-    attempt_number: number;
-    score: number;
-    max_score: number;
-    percentage: number;
-    passed: boolean | null;
-    started_at: string;
-    submitted_at: string | null;
-    graded_at: string | null;
-    question_results?: Array<{
-        question_id: string;
-        sequence_number: number;
-        points: number;
-        result: unknown;
-    }>;
-}
-interface Collection {
-    id: string;
-    name: string;
-    slug: string;
-    description: string | null;
-    status: string;
-    item_count: number;
-    created_at: string;
-    updated_at: string;
-}
-interface CollectionDetail extends Collection {
-    items: Array<{
-        id: string;
-        position: number;
-        assessment: Assessment;
-    }>;
-}
-interface Webhook {
-    id: string;
-    url: string;
-    events: string[];
-    status: string;
-}
-interface WebhookWithSecret extends Webhook {
-    secret: string;
-}
-interface EmbedToken {
-    token: string;
-    expires_at: string;
-    assessment_id: string;
-    learner_ref: string;
-}
-declare class EdpireClient {
-    private apiKey;
-    private baseUrl;
-    private fetchFn;
-    constructor(options: EdpireClientOptions);
-    private request;
-    private requestPaginated;
-    /**
-     * List assessments in your org.
-     *
-     * @param params.status - Filter by status: `"draft"`, `"published"`, or `"archived"`.
-     * @param params.ids - Bulk fetch by IDs (max 50). Comma-separated or array.
-     * @param params.page - Page number (default 1).
-     * @param params.limit - Items per page (default 20, max 100).
-     * @returns Paginated list of assessments with exercise counts.
-     * @throws {EdpireError} 401/403 for auth issues.
-     *
-     * @example
-     * ```typescript
-     * const { items } = await client.getAssessments({ status: "published" })
-     * const { items: batch } = await client.getAssessments({ ids: ["id1", "id2"] })
-     * ```
-     */
-    getAssessments(params?: {
-        status?: string;
-        ids?: string[];
-        page?: number;
-        limit?: number;
-    }): Promise<PaginatedResponse<AssessmentSummary>>;
-    /**
-     * Fetch a single assessment with its exercises and questions.
-     *
-     * Returns content for rendering (no answer keys, ever).
-     *
-     * @param id - Assessment UUID.
-     * @returns Assessment with exercises and questions.
-     * @throws {EdpireError} 404 if not found, 401/403 for auth issues.
-     *
-     * @example
-     * ```typescript
-     * const assessment = await client.getAssessment("abc-123")
-     * console.log(assessment.title, assessment.exercises?.length)
-     * ```
-     */
-    getAssessment(id: string): Promise<Assessment>;
-    /**
-     * Submit a full assessment for grading (headless).
-     *
-     * Creates a submission record, grades all answers, and returns results
-     * synchronously. No Edpire UI involved. Also fires `submission.graded` webhook.
-     *
-     * @param assessmentId - Assessment UUID.
-     * @param options - Learner ref, answers, and optional flags.
-     * @returns Graded result with per-question feedback.
-     * @throws {EdpireError} 404 (not found), 400 (draft/archived), 409 (max attempts), 422 (grading failed).
-     *
-     * @example
-     * ```typescript
-     * const result = await client.submit("assessment-id", {
-     *   learner_ref: "user-123",
-     *   answers: {
-     *     exerciseAnswers: [{
-     *       exerciseId: "ex-1",
-     *       questionAnswers: [{
-     *         questionId: "q-1",
-     *         answers: [{ nodeId: "n1", value: "selected-choice" }],
-     *       }],
-     *     }],
-     *   },
-     * })
-     * console.log(result.score, result.max_score, result.passed)
-     * ```
-     */
-    submit(assessmentId: string, options: SubmitOptions): Promise<GradeResult>;
-    /**
-     * Grade a single question without creating a submission.
-     *
-     * Designed for Duolingo-style flows: immediate per-question feedback,
-     * hearts/lives, practice drills. Stateless — no submission record.
-     *
-     * @param assessmentId - Assessment UUID.
-     * @param options - Exercise ID, question ID, answers, and learner ref.
-     * @returns Correctness result with sanitized per-node feedback.
-     * @throws {EdpireError} 404 (not found), 429 (rate limit exceeded).
-     *
-     * @example
-     * ```typescript
-     * const check = await client.checkQuestion("assessment-id", {
-     *   exercise_id: "ex-1",
-     *   question_id: "q-1",
-     *   answers: [{ nodeId: "n1", value: "typed-answer" }],
-     *   learner_ref: "user-123",
-     * })
-     * if (check.correct) { hearts.keep() } else { hearts.lose() }
-     * ```
-     */
-    checkQuestion(assessmentId: string, options: CheckOptions): Promise<CheckResult>;
-    /**
-     * Fetch a detailed submission with per-question results.
-     *
-     * @param id - Submission UUID.
-     * @returns Full submission with question-level breakdown.
-     * @throws {EdpireError} 404 if not found, 401/403 for auth issues.
-     */
-    getSubmission(id: string): Promise<Submission>;
-    /**
-     * Fetch all submissions for a learner.
-     *
-     * @param learnerRef - Your stable user ID (the `learner_ref` you passed during submit).
-     * @param params.page - Page number (default 1).
-     * @param params.limit - Items per page (default 50, max 100).
-     * @returns Paginated list of submissions.
-     * @throws {EdpireError} 401/403 for auth issues.
-     */
-    getLearnerResults(learnerRef: string, params?: {
-        page?: number;
-        limit?: number;
-    }): Promise<PaginatedResponse<Submission>>;
-    /**
-     * List collections in your org.
-     *
-     * @param params.page - Page number (default 1).
-     * @param params.limit - Items per page (default 20, max 100).
-     * @returns Paginated list of collections with item counts.
-     */
-    getCollections(params?: {
-        page?: number;
-        limit?: number;
-    }): Promise<PaginatedResponse<Collection>>;
-    /**
-     * Fetch a collection with its assessment items.
-     *
-     * @param id - Collection UUID.
-     * @returns Collection detail with ordered assessment items.
-     * @throws {EdpireError} 404 if not found.
-     */
-    getCollection(id: string): Promise<CollectionDetail>;
-    /**
-     * Fetch aggregated results across all assessments in a collection.
-     *
-     * @param id - Collection UUID.
-     * @param params.page - Page number (default 1).
-     * @param params.limit - Items per page (default 50, max 100).
-     * @returns Paginated flat list of submissions with assessment titles.
-     */
-    getCollectionResults(id: string, params?: {
-        page?: number;
-        limit?: number;
-    }): Promise<PaginatedResponse<Submission & {
-        assessment_title: string;
-    }>>;
-    /**
-     * Register a webhook endpoint.
-     *
-     * The secret is returned once only — store it securely for signature verification.
-     *
-     * @param url - HTTPS endpoint URL (http://localhost allowed for dev).
-     * @param events - Event types to subscribe to (e.g., `["submission.graded"]`).
-     * @returns Webhook with secret (shown once).
-     * @throws {EdpireError} 400 for invalid URL or events.
-     */
-    registerWebhook(url: string, events: string[]): Promise<WebhookWithSecret>;
-    /**
-     * List registered webhooks (secrets not included).
-     *
-     * @returns Array of webhooks.
-     */
-    listWebhooks(): Promise<Webhook[]>;
-    /**
-     * Delete a webhook endpoint.
-     *
-     * @param id - Webhook UUID.
-     * @throws {EdpireError} 404 if not found.
-     */
-    deleteWebhook(id: string): Promise<void>;
-    /**
-     * Mint an embed token for browser-side assessment rendering.
-     *
-     * Use this when you want to embed Edpire's assessment UI in your page
-     * via `EdpireAssessment.mount()`. The token is single-use and expires in 1 hour.
-     *
-     * @param assessmentId - Assessment UUID.
-     * @param learnerRef - Your stable user ID.
-     * @returns JWT token and expiration timestamp.
-     * @throws {EdpireError} 404 if assessment not found.
-     */
-    mintEmbedToken(assessmentId: string, learnerRef: string): Promise<EmbedToken>;
-}
-/** Minimal interface covering IncomingMessage + connect/Express-style requests. */
-interface ConnectRequest {
-    method?: string;
-    url?: string;
-    headers: Record<string, string | string[] | undefined>;
-    on(event: "data", listener: (chunk: Uint8Array) => void): ConnectRequest;
-    on(event: "end", listener: () => void): ConnectRequest;
-    on(event: "error", listener: (err: Error) => void): ConnectRequest;
-    on(event: string, listener: (...args: unknown[]) => void): ConnectRequest;
-}
-/** Minimal interface covering ServerResponse + connect/Express-style responses. */
-interface ConnectResponse {
-    statusCode: number;
-    setHeader(name: string, value: string | number | string[]): void;
-    end(data?: string | Uint8Array): void;
-}
-interface EdpireTokenHandlerOptions {
-    /** Your Edpire API key (starts with `edp_live_`). NEVER expose client-side. */
-    apiKey: string;
-    /** Base URL of the Edpire API. Defaults to `"https://edpire.com"`. */
-    baseUrl?: string;
-    /**
-     * Resolve the learner's stable ID from the incoming request.
-     *
-     * Read from YOUR auth/session system — **NEVER** trust a value from the
-     * request body or query string. Return `null` / `undefined` (or throw) to
-     * reject unauthenticated requests with a 401.
-     *
-     * @example Next.js App Router + Better Auth
-     * ```typescript
-     * resolveLearner: async (req) => {
-     *   const session = await auth.api.getSession({ headers: req.headers })
-     *   return session?.user.id ?? null  // null → 401 Unauthorized
-     * }
-     * ```
-     */
-    resolveLearner: (req: Request) => string | null | undefined | Promise<string | null | undefined>;
-    /**
-     * Optionally validate or remap the assessment ID from the request body.
-     *
-     * If omitted, the handler reads `assessmentId` from the POST body JSON and
-     * passes it directly to Edpire. Use this callback to enforce an allow-list,
-     * validate the ID belongs to the learner's course, or map your own IDs to
-     * Edpire UUIDs.
-     *
-     * Throw to reject the request (handler returns 403).
-     *
-     * @example Allow-list
-     * ```typescript
-     * resolveAssessmentId: (req, id) => {
-     *   if (!ALLOWED_IDS.includes(id)) throw new Error("Assessment not permitted")
-     *   return id
-     * }
-     * ```
-     */
-    resolveAssessmentId?: (req: Request, fromBody: string) => string | Promise<string>;
-}
-/**
- * Create a Web-standard token-minting request handler for the Embedded Player.
- *
- * Returns a `(req: Request) => Promise<Response>` that:
- * 1. Calls your `resolveLearner` to get the learner ID from YOUR session.
- * 2. Reads `assessmentId` from the POST body (override with `resolveAssessmentId`).
- * 3. Mints a short-lived, single-use embed token via `EdpireClient.mintEmbedToken()`.
- * 4. Returns `{ token }` or an appropriate HTTP error.
- *
- * The returned function is **Web-standard** (use directly as a Next.js App Router
- * route export). For Express / Node.js http / Vite dev middleware, wrap it with
- * `toNodeHandler()`.
- *
- * @example Next.js App Router
- * ```typescript
- * // app/api/edpire/token/route.ts
- * import { createEdpireTokenHandler } from "@edpire/sdk/client"
- * import { auth } from "@/lib/auth"
- *
- * export const POST = createEdpireTokenHandler({
- *   apiKey: process.env.EDPIRE_API_KEY!,
- *   resolveLearner: async (req) => {
- *     const session = await auth.api.getSession({ headers: req.headers })
- *     return session?.user.id ?? null   // null → 401 Unauthorized
- *   },
- * })
- * ```
- *
- * @example Express / Vite dev middleware
- * ```typescript
- * import { createEdpireTokenHandler, toNodeHandler } from "@edpire/sdk/client"
- *
- * const tokenHandler = toNodeHandler(createEdpireTokenHandler({
- *   apiKey: process.env.EDPIRE_API_KEY!,
- *   resolveLearner: (req) => req.session?.userId ?? null,
- * }))
- * app.post("/api/edpire/token", tokenHandler)
- * ```
- */
-declare function createEdpireTokenHandler(opts: EdpireTokenHandlerOptions): (req: Request) => Promise<Response>;
-/**
- * Adapt a Web-standard token handler (from `createEdpireTokenHandler`) to a
- * Node.js-style connect middleware compatible with Express, Fastify, and Vite's
- * `configureServer` dev middleware.
- *
- * @example Express
- * ```typescript
- * import express from "express"
- * import { createEdpireTokenHandler, toNodeHandler } from "@edpire/sdk/client"
- *
- * const app = express()
- * app.post("/api/edpire/token", toNodeHandler(createEdpireTokenHandler({
- *   apiKey: process.env.EDPIRE_API_KEY!,
- *   resolveLearner: (req) => req.session?.userId ?? null,
- * })))
- * ```
- *
- * @example Vite dev middleware
- * ```typescript
- * // vite.config.ts  (dev only — for production use a real server)
- * configureServer(server) {
- *   server.middlewares.use("/api/edpire/token", toNodeHandler(tokenHandler))
- * }
- * ```
- */
-declare function toNodeHandler(handler: (req: Request) => Promise<Response>): (req: ConnectRequest, res: ConnectResponse) => void;
-
-export { type Assessment, type AssessmentExercise, type AssessmentQuestion, type AssessmentSummary, type CheckOptions, type CheckResult, type Collection, type CollectionDetail, EdpireClient, type EdpireClientOptions, EdpireError, type EdpireTokenHandlerOptions, type EmbedToken, type GradeResult, type PaginatedResponse, type StoredAnswer, type Submission, type SubmitOptions, type Webhook, type WebhookWithSecret, createEdpireTokenHandler, toNodeHandler };