@edpire/sdk 0.6.10 → 0.6.12

package/examples/vite-express/index.html

@@ -3,7 +3,7 @@
   <head>
     <meta charset="UTF-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1.0" />
-    <title>Edpire SDK — Vite + Express example</title>
+    <title>Edpire Vite and Express example</title>
     <style>
       * { box-sizing: border-box; }
       body { margin: 0; }

package/examples/vite-express/package.json

@@ -5,19 +5,17 @@
   "type": "module",
   "scripts": {
     "dev": "concurrently -k -n SERVER,VITE -c cyan,magenta \"tsx server.ts\" \"vite\"",
-    "build": "vite build && tsc -p tsconfig.server.json",
+    "build": "vite build && tsc --noEmit -p tsconfig.server.json",
     "preview": "tsx server.ts",
-    "type-check": "tsc --noEmit"
+    "type-check": "tsc --noEmit && tsc --noEmit -p tsconfig.server.json"
   },
   "dependencies": {
-    "@edpire/sdk": "^0.6.0",
-    "cors": "^2.8.5",
+    "@edpire/sdk": "^0.6.10",
     "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",
@@ -27,6 +25,6 @@
     "dotenv": "^16.3.1",
     "tsx": "^4.7.0",
     "typescript": "^5.0.0",
-    "vite": "^5.0.0"
+    "vite": "^6.0.0"
   }
 }

package/examples/vite-express/server.ts

@@ -1,96 +1,102 @@
-/**
- * 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}`)
-  }
-})
+/**
+ * The Express side: two routes, plus static files in production.
+ *
+ *   GET  /api/edpire/assessments   what is published, so the page can list it
+ *   POST /api/edpire/token         a short-lived token for one learner
+ *
+ * In development Vite serves the page on 5173 and proxies /api here, so the
+ * browser only ever talks to one origin and no CORS is involved.
+ *
+ *   npm run dev      both, together
+ *   npm run build && npm run preview
+ */
+import "dotenv/config"
+import express from "express"
+import path from "node:path"
+import { fileURLToPath } from "node:url"
+import { createEdpireTokenHandler, toNodeHandler, EdpireClient } 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()
+const edpire = new EdpireClient({ apiKey: process.env.EDPIRE_API_KEY! })
+
+/**
+ * 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. `status=published` matters: a draft
+ * cannot be played.
+ */
+app.get("/api/edpire/assessments", async (_req, res) => {
+  try {
+    const { items } = await edpire.getAssessments({ status: "published", limit: 5 })
+    res.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.
+    res.status(502).json({
+      error:
+        `Could not list assessments: ${err instanceof Error ? err.message : err}. ` +
+        "Check EDPIRE_API_KEY, and that this machine can reach edpire.com.",
+    })
+  }
+})
+
+/**
+ * toNodeHandler adapts the Web-standard handler to Express's (req, res).
+ * Without it the request hangs until the browser times out.
+ *
+ * Mount it BEFORE any body parser. The handler reads the request stream
+ * itself, and a parser that already drained it makes this hang too.
+ */
+app.post(
+  "/api/edpire/token",
+  toNodeHandler(
+    createEdpireTokenHandler({
+      apiKey: process.env.EDPIRE_API_KEY!,
+
+      /**
+       * ─────────────────────────────────────────────────────────────────────
+       * REPLACE THIS. It decides whose results get recorded.
+       * ─────────────────────────────────────────────────────────────────────
+       *
+       * `req` is a Web-standard Request rebuilt from the Node request, so
+       * Express extras like `req.session` and `req.cookies` do NOT exist here.
+       * Read the raw header and do your own lookup:
+       *
+       *   const sid = parseCookie(req.headers.get("cookie"), "sid")
+       *   return sid ? (await sessionStore.get(sid))?.userId ?? null : null
+       *
+       * Returning null rejects the request with 401 and mints nothing.
+       *
+       * Never read the learner from the request body. If the browser can name
+       * the learner, any learner can submit results as any other.
+       */
+      resolveLearner: async () => "demo-learner-001",
+    }),
+  ),
+)
+
+// Production only: serve the built page, with an SPA fallback for client routes.
+if (!isDev) {
+  const dist = path.join(__dirname, "dist")
+  app.use(express.static(dist))
+  app.get(/^(?!\/api).*$/, (_req, res) => res.sendFile(path.join(dist, "index.html")))
+}
+
+app.listen(PORT, () => {
+  console.log(
+    isDev
+      ? `[server] ready on :${PORT}. Vite serves the page on :5173 and proxies /api here.`
+      : `[server] ready on http://localhost:${PORT}`,
+  )
+})

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

@@ -1,56 +1,128 @@
-/**
- * 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" }}
-    />
-  )
-}
+/**
+ * The whole integration, in two steps.
+ *
+ * 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.
+ *
+ * Your API key never reaches the browser.
+ */
+import { useEffect, useState } from "react"
+import { EdpireAssessmentPlayer } from "@edpire/sdk/react"
+
+type Assessment = { id: string; title: string; exerciseCount: number | null }
+
+export default function App() {
+  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 (
+      <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 (
+    <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/vite-express/tsconfig.server.json

@@ -1,12 +1,12 @@
 {
+  // tsconfig.json only includes src/, so server.ts would otherwise never be
+  // type-checked. The server is run by tsx, which strips types without
+  // checking them, so nothing else would catch a mistake in it.
   "extends": "./tsconfig.json",
   "compilerOptions": {
-    "noEmit": false,
-    "outDir": "dist-server",
-    "module": "ESNext",
-    "moduleResolution": "Bundler",
-    "target": "node18",
-    "allowImportingTsExtensions": false
+    "lib": ["ES2022"],
+    "target": "ES2022",
+    "types": ["node"]
   },
   "include": ["server.ts"]
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@edpire/sdk",
-  "version": "0.6.10",
+  "version": "0.6.12",
   "description": "Embeddable JS SDK for Edpire assessments",
   "license": "SEE LICENSE IN LICENSE",
   "homepage": "https://docs.edpire.com/developer/sdk/overview",

package/examples/nextjs/app/globals.css

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