@edpire/sdk 0.6.10 → 0.6.12

package/examples/nextjs/.env.example

@@ -1,6 +1,4 @@
-# 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.
+# Your Edpire API key, from edpire.com -> Integrations -> API keys.
+# Server-side only. Never prefix it with NEXT_PUBLIC_, which would publish it
+# in the browser bundle.
 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

@@ -1,66 +1,76 @@
-# 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
-```
+# Edpire in Next.js
+
+A working assessment player in a Next.js App Router app. Three files are the
+whole integration.
+
+<table>
+<tr>
+<td width="33%"><img src="docs/screenshots/01-pick.jpg" alt="A list of published assessments, each with a title and an exercise count" /></td>
+<td width="33%"><img src="docs/screenshots/02-play.jpg" alt="An assessment open in the Edpire player" /></td>
+<td width="33%"><img src="docs/screenshots/03-graded.jpg" alt="The same assessment after submitting, with per-question marks and the answer key" /></td>
+</tr>
+<tr>
+<td align="center"><sub><b>1.</b> Pick by title, not by ID</sub></td>
+<td align="center"><sub><b>2.</b> The player</sub></td>
+<td align="center"><sub><b>3.</b> Graded in place</sub></td>
+</tr>
+</table>
+
+Everything from screen 2 onward is the SDK. You write screen 1 and the two API
+routes.
+
+| File | What it does |
+|---|---|
+| `app/api/edpire/assessments/route.ts` | Lists what is published, so the page can show titles |
+| `app/api/edpire/token/route.ts` | Mints a short-lived token for one learner |
+| `app/page.tsx` | Shows the list, then renders the player |
+
+## Run it
+
+```bash
+cp .env.example .env.local     # paste your EDPIRE_API_KEY
+npm install
+npm run dev
+```
+
+Open http://localhost:3000. The page lists your published assessments; click one
+to play it.
+
+**Add `http://localhost:3000` to your allow-list first**, at edpire.com under
+Integrations, Origins, Allowed Embed Origins. Without it the player says
+`Origin not allowed` and names the origin to add, and `onError` fires with
+`ORIGIN_NOT_ALLOWED`. Add your production domain before you deploy.
+
+## Why the token endpoint exists
+
+Your API key can read and write everything in your organisation, so it cannot go
+in the browser. The endpoint keeps it on the server and hands the browser a
+token instead: single use, one learner, one assessment, expiring in two hours.
+
+It also answers *which learner is this?* in a way the browser cannot forge. That
+is `resolveLearner`, and replacing it is the one change you must make:
+
+```typescript
+resolveLearner: async (req) => {
+  const session = await auth.api.getSession({ headers: req.headers })
+  return session?.user.id ?? null      // null returns 401
+}
+```
+
+Until you do, every attempt is recorded against `demo-learner-001`.
+
+## Two things worth knowing
+
+**The player fills its container**, so the container needs a real height. Without
+one it collapses to zero and the player renders invisibly. Hence
+`height: 100vh` in `page.tsx`.
+
+**Treat `onComplete` as a UI hint.** It is the fastest way to show a score, and it
+is a client callback. Record the authoritative result server-side from the
+[`submission.graded` webhook](https://docs.edpire.com/developer/webhooks).
+
+## Next steps
+
+- [Embedded Player](https://docs.edpire.com/developer/sdk/embedded-player), every prop and callback
+- [Webhooks](https://docs.edpire.com/developer/webhooks), for recording results
+- [Troubleshooting](https://docs.edpire.com/developer/sdk/troubleshooting)

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

@@ -0,0 +1,36 @@
+/**
+ * The assessments this learner can play.
+ *
+ * Your API key is used here, on the server. The browser receives only titles
+ * and IDs, neither of which is secret, and shows them for the learner to pick.
+ *
+ * `status=published` matters: a draft cannot be played.
+ */
+import { EdpireClient } from "@edpire/sdk/client"
+
+const client = new EdpireClient({ apiKey: process.env.EDPIRE_API_KEY! })
+
+export async function GET() {
+  try {
+    const { items } = await client.getAssessments({ status: "published", limit: 5 })
+
+    return Response.json({
+      assessments: items.map((a) => ({
+        id: a.id,
+        title: a.title,
+        exerciseCount: a.exercise_count ?? null,
+      })),
+    })
+  } catch (err) {
+    // "fetch failed" on its own tells the reader nothing, so name the two
+    // things it is almost always caused by.
+    return Response.json(
+      {
+        error:
+          `Could not list assessments: ${err instanceof Error ? err.message : err}. ` +
+          "Check EDPIRE_API_KEY, and that this machine can reach edpire.com.",
+      },
+      { status: 502 },
+    )
+  }
+}

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

@@ -1,11 +1,8 @@
 /**
- * Token-minting endpoint for the Edpire Embedded Player.
+ * Mints a short-lived embed token for one learner and one assessment.
  *
- * 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.
+ * The browser POSTs { assessmentId } and receives { token }. Your API key stays
+ * here: if it reached the browser it would be readable by anyone.
  */
 import { createEdpireTokenHandler } from "@edpire/sdk/client"
 
@@ -13,26 +10,22 @@ 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:
+   * ───────────────────────────────────────────────────────────────────────
+   * REPLACE THIS. It decides whose results get recorded.
+   * ───────────────────────────────────────────────────────────────────────
    *
-   * @example Next.js + NextAuth
-   *   const session = await getServerSession(req, res, authOptions)
-   *   return session?.user?.id ?? null
+   * Read the learner from your own session:
    *
-   * @example Next.js + Better Auth
    *   const session = await auth.api.getSession({ headers: req.headers })
-   *   return session?.user.id ?? null
+   *   return session?.user.id ?? null            // Better Auth
+   *
+   *   const session = await getServerSession(authOptions)
+   *   return session?.user.id ?? null            // NextAuth
+   *
+   * Returning null rejects the request with 401 and mints nothing.
    *
-   * Returning null → 401 Unauthorized (no token minted).
-   * Never read the learner ID from the request body — that's an open relay.
+   * Never read the learner from the request body. If the browser can name the
+   * learner, any learner can submit results as any other.
    */
-  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
-  },
+  resolveLearner: async () => "demo-learner-001",
 })

package/examples/nextjs/app/layout.tsx

@@ -1,7 +1,7 @@
 import type { Metadata } from "next"
 
 export const metadata: Metadata = {
-  title: "Edpire SDK — Next.js example",
+  title: "Edpire Next.js example",
 }
 
 export default function RootLayout({ children }: { children: React.ReactNode }) {

package/examples/nextjs/app/page.tsx

@@ -1,51 +1,130 @@
 "use client"
 
 /**
- * Example page: embed an Edpire assessment player.
+ * The whole integration, in two steps.
  *
- * 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.
+ * 1. Ask your own server what is published, and show the titles.
+ * 2. Render <EdpireAssessmentPlayer> for whichever the learner picks. It fetches
+ *    a token from /api/edpire/token, loads the assessment, grades the
+ *    submission and shows per-question feedback.
  *
- * You never see the API key in the browser.
+ * Your API key never reaches the browser.
  */
+import { useEffect, useState } from "react"
 import { EdpireAssessmentPlayer } from "@edpire/sdk/react"
 
-const ASSESSMENT_ID = process.env.NEXT_PUBLIC_ASSESSMENT_ID
+type Assessment = { id: string; title: string; exerciseCount: number | null }
 
 export default function Page() {
-  if (!ASSESSMENT_ID) {
+  const [assessments, setAssessments] = useState<Assessment[] | null>(null)
+  const [error, setError] = useState<string | null>(null)
+  const [playing, setPlaying] = useState<string | null>(null)
+
+  function load() {
+    setError(null)
+    setAssessments(null)
+    fetch("/api/edpire/assessments")
+      .then((r) => r.json())
+      .then((data) => (data.error ? setError(data.error) : setAssessments(data.assessments)))
+      .catch((e) => setError(String(e)))
+  }
+
+  useEffect(load, [])
+
+  if (playing) {
     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>
+      <EdpireAssessmentPlayer
+        tokenEndpoint="/api/edpire/token"
+        assessmentId={playing}
+        onComplete={(result) => {
+          // A UI hint. Record the authoritative result server-side from the
+          // submission.graded webhook.
+          console.log("complete", result.score, "/", result.max_score)
+        }}
+        onError={(err) => setError(`${err.code}: ${err.message}`)}
+        // The player fills its container, so the container needs a real height.
+        // Without one it collapses and the player renders invisibly.
+        style={{ width: "100%", height: "100vh" }}
+      />
     )
   }
 
   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" }}
-    />
+    <main style={styles.page}>
+      <h1 style={styles.title}>Edpire example</h1>
+
+      {error ? (
+        <>
+          <p style={styles.error}>{error}</p>
+          <button onClick={load} style={styles.retry}>Try again</button>
+        </>
+      ) : assessments === null ? (
+        <p style={styles.muted}>Loading...</p>
+      ) : assessments.length === 0 ? (
+        <Empty />
+      ) : (
+        <>
+          <p style={styles.muted}>Published in your organisation. Choose one to play it.</p>
+          {assessments.map((a) => (
+            <button key={a.id} onClick={() => setPlaying(a.id)} style={styles.card}>
+              <span style={styles.cardTitle}>{a.title}</span>
+              {a.exerciseCount !== null && (
+                <span style={styles.cardMeta}>{a.exerciseCount} exercise(s)</span>
+              )}
+            </button>
+          ))}
+        </>
+      )}
+    </main>
   )
 }
+
+/** A new organisation has nothing published, and the fix is in Edpire. */
+function Empty() {
+  return (
+    <div style={styles.empty}>
+      <p>
+        Nothing is published in this organisation yet, so there is nothing to open. Create an
+        assessment in Edpire, publish it, then reload. Drafts do not appear here.
+      </p>
+      <a href="https://docs.edpire.com/quickstart" style={styles.link}>
+        docs.edpire.com/quickstart
+      </a>
+    </div>
+  )
+}
+
+const styles: Record<string, React.CSSProperties> = {
+  page: { maxWidth: 640, margin: "0 auto", padding: 32, fontFamily: "system-ui, sans-serif" },
+  title: { fontSize: 24, marginBottom: 4 },
+  muted: { color: "#565b66", fontSize: 14 },
+  error: { color: "#d23b2b", fontSize: 14, whiteSpace: "pre-wrap" },
+  card: {
+    display: "flex",
+    flexDirection: "column",
+    alignItems: "flex-start",
+    gap: 4,
+    width: "100%",
+    padding: 16,
+    marginTop: 10,
+    border: "1px solid #e7e5e0",
+    borderRadius: 12,
+    background: "#fff",
+    cursor: "pointer",
+    textAlign: "left",
+    font: "inherit",
+  },
+  cardTitle: { fontSize: 15, fontWeight: 600 },
+  cardMeta: { fontSize: 12, color: "#8d93a0" },
+  empty: { marginTop: 12, color: "#565b66", fontSize: 14, lineHeight: 1.6 },
+  retry: {
+    marginTop: 12,
+    padding: "8px 18px",
+    border: "1px solid #e7e5e0",
+    borderRadius: 999,
+    background: "#fff",
+    cursor: "pointer",
+    font: "inherit",
+  },
+  link: { color: "#d23b2b" },
+}

package/examples/nextjs/next.config.ts

@@ -1,8 +1,9 @@
 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.
+  // Next 16 writes AGENTS.md and CLAUDE.md into the project on first run. This
+  // is a template you are meant to copy from, so keep it to your own files.
+  agentRules: false,
 }
 
 export default nextConfig

package/examples/nextjs/package.json

@@ -8,8 +8,8 @@
     "start": "next start"
   },
   "dependencies": {
-    "@edpire/sdk": "^0.6.0",
-    "next": "^15.0.0",
+    "@edpire/sdk": "^0.6.10",
+    "next": "^16.0.0",
     "react": "^19.0.0",
     "react-dom": "^19.0.0"
   },

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

@@ -1,10 +1,7 @@
-# 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.
+# Your Edpire API key, from edpire.com -> Integrations -> API keys.
+# Server-side only. Never prefix it with VITE_, which would publish it 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 for the Express server. Vite serves the page on 5173 and proxies here.
 PORT=3001

package/examples/vite-express/README.md

@@ -1,69 +1,89 @@
-# 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
-```
+# Edpire in Vite and Express
+
+A working assessment player with a React frontend and an Express backend. Two
+files are the whole integration.
+
+<table>
+<tr>
+<td width="33%"><img src="docs/screenshots/01-pick.jpg" alt="A list of published assessments, each with a title and an exercise count" /></td>
+<td width="33%"><img src="docs/screenshots/02-play.jpg" alt="An assessment open in the Edpire player" /></td>
+<td width="33%"><img src="docs/screenshots/03-graded.jpg" alt="The same assessment after submitting, with per-question marks and the answer key" /></td>
+</tr>
+<tr>
+<td align="center"><sub><b>1.</b> Pick by title, not by ID</sub></td>
+<td align="center"><sub><b>2.</b> The player</sub></td>
+<td align="center"><sub><b>3.</b> Graded in place</sub></td>
+</tr>
+</table>
+
+Everything from screen 2 onward is the SDK. You write screen 1 and the server.
+
+| File | What it does |
+|---|---|
+| `server.ts` | Lists what is published, and mints tokens |
+| `src/App.tsx` | Shows the list, then renders the player |
+
+## Run it
+
+```bash
+cp .env.example .env      # paste your EDPIRE_API_KEY
+npm install
+npm run dev
+```
+
+That starts both: Express on 3001, Vite on 5173. Open http://localhost:5173.
+The page lists your published assessments; click one to play it.
+
+**Add `http://localhost:5173` to your allow-list first**, at edpire.com under
+Integrations, Origins, Allowed Embed Origins. Without it the player says
+`Origin not allowed` and names the origin to add, and `onError` fires with
+`ORIGIN_NOT_ALLOWED`. Add your production domain before you deploy.
+
+Note the port: the browser talks to Vite on **5173**, which proxies `/api` to
+Express. Adding 3001 instead is a common ten-minute detour.
+
+## Why the token endpoint exists
+
+Your API key can read and write everything in your organisation, so it cannot go
+in the browser. The endpoint keeps it on the server and hands the browser a
+token instead: single use, one learner, one assessment, expiring in two hours.
+
+It also answers *which learner is this?* in a way the browser cannot forge. That
+is `resolveLearner`, and replacing it is the one change you must make:
+
+```typescript
+resolveLearner: async (req) => {
+  const sid = parseCookie(req.headers.get("cookie"), "sid")
+  return sid ? (await sessionStore.get(sid))?.userId ?? null : null
+}
+```
+
+Until you do, every attempt is recorded against `demo-learner-001`.
+
+## Three things worth knowing
+
+**`req` is a Web-standard Request**, not an Express one, so `req.session` and
+`req.cookies` do not exist inside `resolveLearner`. Read the raw cookie header
+and do your own lookup.
+
+**Mount the token route before any body parser.** The handler reads the request
+stream itself, and a parser that already drained it makes the request hang.
+
+**The player fills its container**, so the container needs a real height. Without
+one it collapses to zero and the player renders invisibly. Hence
+`height: 100vh` in `App.tsx`.
+
+## Production
+
+```bash
+npm run build && npm run preview
+```
+
+Express then serves the built page and the two API routes from one origin, so
+the Vite proxy is no longer involved.
+
+## Next steps
+
+- [Embedded Player](https://docs.edpire.com/developer/sdk/embedded-player), every prop and callback
+- [Webhooks](https://docs.edpire.com/developer/webhooks), for recording results
+- [Troubleshooting](https://docs.edpire.com/developer/sdk/troubleshooting)