@tinyweb_dev/oe-exam-sdk

SDK tái sử dụng cho hệ thống OE Exam: màn tạo đề, quản lý câu hỏi, làm bài, xem kết quả, theme giao diện và MCP tools.

Cài đặt

npm install @tinyweb_dev/oe-exam-sdk

Cách dùng nhanh

'use client';

import {
  CreateExamPageContainer,
  ExamQuestionsPageContainer,
  ExamTakingPageContainer,
  ResultReviewPageContainer,
} from '@tinyweb_dev/oe-exam-sdk';
import {
  createExamCreateApi,
  createExamQuestionsApi,
  createExamTakingApi,
  createResultReviewApi,
} from '@tinyweb_dev/oe-exam-sdk/api';

const baseUrl = process.env.NEXT_PUBLIC_API_URL;

export function CreateExamPage({ router }) {
  return (
    <CreateExamPageContainer
      api={createExamCreateApi({ baseUrl })}
      onNavigate={(href) => router.push(href)}
    />
  );
}

export function ExamQuestionsPage({ examId, router }) {
  return (
    <ExamQuestionsPageContainer
      examId={examId}
      api={createExamQuestionsApi({ baseUrl })}
      onNavigate={(href) => router.push(href)}
    />
  );
}

export function ExamTakePage({ examId, router }) {
  return (
    <ExamTakingPageContainer
      examId={examId}
      api={createExamTakingApi({ baseUrl })}
      onNavigate={(href) => router.replace(href)}
    />
  );
}

export function ResultReviewPage({ attemptId, token, router }) {
  return (
    <ResultReviewPageContainer
      attemptId={attemptId}
      token={token}
      api={createResultReviewApi({ baseUrl })}
      onNavigate={(href) => router.push(href)}
    />
  );
}

Entry points

@tinyweb_dev/oe-exam-sdk                       # export tổng hợp thường dùng
@tinyweb_dev/oe-exam-sdk/api                   # API adapters, constants, types
@tinyweb_dev/oe-exam-sdk/shared                # shared constants/types/helpers
@tinyweb_dev/oe-exam-sdk/mcp                   # MCP server entry và tools
@tinyweb_dev/oe-exam-sdk/components            # shared UI components
@tinyweb_dev/oe-exam-sdk/components/exams      # màn tạo đề / câu hỏi / làm bài
@tinyweb_dev/oe-exam-sdk/components/exams/take # màn làm bài + renderer generic
@tinyweb_dev/oe-exam-sdk/components/questions  # hệ thống tạo câu hỏi
@tinyweb_dev/oe-exam-sdk/components/themes     # cambridge-yle, english-certification, summer-sky
@tinyweb_dev/oe-exam-sdk/components/results    # màn xem chi tiết kết quả

API adapters

SDK không fix cứng API client. Host app có thể truyền adapter riêng qua prop api, hoặc dùng adapter mặc định:

import {
  createExamCreateApi,
  createExamQuestionsApi,
  createExamTakingApi,
  createResultReviewApi,
} from '@tinyweb_dev/oe-exam-sdk/api';

Các adapter mặc định nhận:

{
  baseUrl?: string;
  fetcher?: typeof fetch;
  headers?: HeadersInit;
}

createExamTakingApi đã bao gồm các API cần cho màn làm bài: start/resume attempt, questions, save answers, submit, upload audio, proctoring snapshot, realtime grading, grading summary/status/detail, room/attempt detail và keepalive save.

Theme làm bài

ExamTakingPageContainer tự chọn layout theo examTemplate.theme:

ENGLISH_CERTIFICATION -> EnglishCertificationExamLayout
CAMBRIDGE_YLE         -> CambridgeYleExamLayout
SUMMER_SKY            -> SummerSkyLayout
khác / rỗng           -> default SDK layout

Renderer câu hỏi trong màn làm bài hiện là GenericQuestionRenderer.

Màn xem kết quả

<ResultReviewPageContainer
  attemptId={attemptId}
  token={token}
  api={createResultReviewApi({ baseUrl })}
  topActionsSlot={null}
  beforeReportSlot={null}
  afterReportSlot={null}
/>

Các phần phụ thuộc app chính như gift dialog, upgrade modal, summary video/remotion nên truyền qua slot từ host app.

MCP server

SDK expose bin:

oe-exam-mcp

Chạy bằng PAT/API token. Nếu token có dạng oeexam_..., MCP tự gửi qua X-API-Key; token khác sẽ gửi qua Authorization: Bearer.

OE_API_URL=http://localhost:3000 OE_API_TOKEN=... npx oe-exam-mcp

Tools hiện có:

exam_templates_search      # tìm template qua filter name:like, lấy id để truyền examTemplateId
exam_template_get          # lấy templatePayload để truyền vào template
exam_question_template_get  # generate API-format questions từ template.parts
exam_json_template_generate # tạo JSON skeleton từ templateTitle/templateId để user edit trước
exam_create_from_json       # tạo exam từ JSON thân thiện: { name, templateTitle/templateId, parts: [{ questions: [...] }] }
exam_create_with_questions # tạo exam, patch template, tạo questions qua /manage/questions/batch
exam_result_get            # xem result review theo attemptId, hỗ trợ token public link

Luồng tạo exam nhanh qua MCP:

1. Gọi exam_json_template_generate với templateTitle hoặc templateId để tạo JSON skeleton theo template.parts và ghi ra file `<slug-title>.json`.
2. User/Roo sửa `parts[].questions[]` trong file JSON đó.
3. Gọi exam_create_from_json với nội dung JSON đã sửa. Tool tự search/get template, patch template, map questions theo template.parts rồi gọi /manage/questions/batch.

Prompt tạo file JSON skeleton trong Roo:

Gọi MCP tool exam_json_template_generate với input:
{
  "templateTitle": "Achievers 2026 Round 1",
  "name": "Sample exam",
  "examLevel": "A1",
  "difficulty": "MEDIUM",
  "durationMinutes": 45
}

Sau khi sửa file JSON, gọi create:

Đọc file JSON đã sửa rồi gọi MCP tool exam_create_from_json với nội dung file đó.

Ví dụ JSON thân thiện:

{
  "name": "Sample exam",
  "templateTitle": "Achievers 2026 Round 1",
  "totalScore": 3,
  "examLevel": "A1",
  "difficulty": "MEDIUM",
  "durationMinutes": 45,
  "parts": [
    {
      "name": "Part 1",
      "questions": [
        { "question": "Câu 1", "options": ["A", "B", "C", "D", "E"], "answer": "A" }
      ]
    }
  ]
}

Mock API

Dùng cho demo/storybook/test nhẹ:

import {
  createMockCreateExamApi,
  createMockExamQuestionsApi,
  createMockExamTakingApi,
  createMockResultReviewApi,
} from '@tinyweb_dev/oe-exam-sdk/api';

Ghi chú tích hợp

• Không cần provider toàn cục.
• Các tích hợp host-system nên đi qua props/API adapter.
• Upload file trong component mặc định dùng blob: URL cục bộ; API upload thật nên truyền từ host app khi cần.

Kiểm tra local

Trong repo này:

npm --prefix sdk run build

Nếu chạy app dev:

npm run dev
# http://localhost:3000/dev/exam-sdk

Publish

cd sdk
npm version patch
npm publish --access public