@edpire/sdk 0.6.2 → 0.6.3

package/dist/client.d.mts

@@ -0,0 +1,540 @@
+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 };

package/examples/vite-express/package.json

@@ -2,6 +2,7 @@
   "name": "edpire-sdk-example-vite-express",
   "version": "0.1.0",
   "private": true,
+  "type": "module",
   "scripts": {
     "dev": "concurrently -k -n SERVER,VITE -c cyan,magenta \"tsx server.ts\" \"vite\"",
     "build": "vite build && tsc -p tsconfig.server.json",

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

@@ -4,7 +4,7 @@
     "noEmit": false,
     "outDir": "dist-server",
     "module": "ESNext",
-    "moduleResolution": "node",
+    "moduleResolution": "Bundler",
     "target": "node18",
     "allowImportingTsExtensions": false
   },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@edpire/sdk",
-  "version": "0.6.2",
+  "version": "0.6.3",
   "description": "Embeddable JS SDK for Edpire assessments",
   "license": "SEE LICENSE IN LICENSE",
   "homepage": "https://docs.edpire.com/developer/sdk/overview",
@@ -32,8 +32,9 @@
       "types": "./dist/react.d.mts"
     },
     "./client": {
+      "types": "./dist/client.d.mts",
       "import": "./dist/client.mjs",
-      "types": "./dist/client.d.mts"
+      "default": "./dist/client.mjs"
     },
     "./styles/runtime-utilities.css": "./src/styles/runtime-utilities.css",
     "./styles/shell.css": "./src/styles/shell.css"