@edpire/sdk 0.6.3 → 0.6.5

package/examples/nextjs/README.md

@@ -1,66 +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
-```
+# 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 → Integrations → Security tab → Allowed Embed 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/vite-express/README.md

@@ -1,69 +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
-```
+# 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 → Integrations → Security tab → Allowed Embed 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/server.ts

@@ -1,84 +1,96 @@
-/**
- * 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}`)
-  }
-})
+/**
+ * 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:
+     *
+     * IMPORTANT: `req` is a Web-standard Request, not an Express request.
+     * `req.session` and `req.cookies` do NOT exist here — read the raw header
+     * and do your own lookup, as below.
+     *
+     * @example session store
+     *   resolveLearner: async (req) => {
+     *     const sid = parseCookie(req.headers.get("cookie"), "sid")
+     *     return sid ? (await sessionStore.get(sid))?.userId ?? null : null
+     *   }
+     *
+     * @example JWT
+     *   resolveLearner: (req) => {
+     *     const token = parseCookie(req.headers.get("cookie"), "token")
+     *     return token ? jwt.verify(token, JWT_SECRET).userId ?? null : null
+     *   }
+     *
+     * Returning null → 401 (no token minted).
+     */
+    resolveLearner: (req) => {
+      // In development, use a fixed test ID so the player works out of the box.
+      // Replace this with your real session logic before going to production —
+      // always derived from the cookie header, never from the request body.
+      if (isDev) return "dev-user-001"
+
+      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

@@ -1,56 +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" }}
-    />
-  )
-}
+/**
+ * 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 Embed Origins* (Integrations -> Security)
+        // 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@edpire/sdk",
-  "version": "0.6.3",
+  "version": "0.6.5",
   "description": "Embeddable JS SDK for Edpire assessments",
   "license": "SEE LICENSE IN LICENSE",
   "homepage": "https://docs.edpire.com/developer/sdk/overview",
@@ -70,8 +70,8 @@
     "@tailwindcss/oxide": "^4.2.0",
     "@types/react": "^19.2.14",
     "@types/react-dom": "^19.2.3",
-    "@youssefalmia/edpire-runtime": "^3.2.0",
-    "@youssefalmia/edpire-schema": "^5.1.0",
+    "@youssefalmia/edpire-runtime": "^3.13.0",
+    "@youssefalmia/edpire-schema": "^5.5.0",
     "tailwindcss": "^3.4.0",
     "tsup": "^8.5.1",
     "typescript": "^5.0.0"
@@ -81,6 +81,7 @@
     "build:css": "node scripts/gen-runtime-css.mjs",
     "build:shell-css": "node scripts/gen-shell-css.mjs",
     "dev": "pnpm build:css && pnpm build:shell-css && tsup --watch",
-    "type-check": "tsc --noEmit"
+    "type-check": "tsc --noEmit",
+    "check:doc-versions": "node ../../scripts/check-doc-versions.mjs"
   }
 }