@edpire/sdk 0.6.0 → 0.6.1

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.1",
   "description": "Embeddable JS SDK for Edpire assessments",
   "license": "SEE LICENSE IN LICENSE",
   "homepage": "https://docs.edpire.com/developer/sdk/overview",
@@ -40,7 +40,8 @@
   },
   "files": [
     "dist",
-    "src/styles"
+    "src/styles",
+    "examples"
   ],
   "dependencies": {
     "@dnd-kit/core": "^6.3.1",