broker-core-sdk 1.0.0 → 1.0.2

package/docs/codebase/ARCHITECTURE.md

@@ -1,37 +0,0 @@
-# Architecture
-
-## Core Sections (Required)
-
-### 1) Architectural Style
-
-- Primary style: Library / SDK (Functional Programming)
-- Why this classification: Stated in `README.md` that it is designed with Functional Programming and Tree-shaking.
-- Primary constraints: Must be framework agnostic (Vanilla TS), no Magic Strings, must use strict Discriminated Union types.
-
-### 2) System Flow
-
-```text
-[Consumer App] -> [Core SDK Export (src/index.ts)] -> [Pure Function Engine (e.g. game-engine.ts)] -> [Result]
-```
-
-### 3) Layer/Module Responsibilities
-
-| Layer or module | Owns | Must not own | Evidence |
-|-----------------|------|--------------|----------|
-| `src/engines` | Algorithmic logic (Spaced Repetition, Game Checks) | State management, UI | `README.md` |
-| `src/types` | Data definitions and Constants | Implementations | `README.md` |
-
-### 4) Reused Patterns
-
-| Pattern | Where found | Why it exists |
-|---------|-------------|---------------|
-| Discriminated Union | `src/types/elements.ts` (`SlideElement`) | To map structures automatically and ensure Type-safety across the ecosystem. |
-
-### 5) Known Architectural Risks
-
-- [TODO] Expanding types might require significant refactoring across the `ElementDataMap`.
-
-### 6) Evidence
-
-- `README.md`
-- `src/index.ts`

package/docs/codebase/CONCERNS.md

@@ -1,19 +0,0 @@
-# Concerns and Technical Debt
-
-## Core Sections (Required)
-
-### 1) Technical Debt & TODOs
-
-- NONE detected in code comments.
-
-### 2) High-Churn Areas
-
-- `README.md` (4 commits)
-- `src/types/slide-element.ts` (4 commits) - Indicates high activity around the core element types.
-- `src/engines/game-engine.ts` (3 commits)
-- `src/engines/learning-engine.ts` (3 commits)
-- `src/types/index.ts` (3 commits)
-
-### 3) Evidence
-
-- Scan output

package/docs/codebase/CONVENTIONS.md

@@ -1,22 +0,0 @@
-# Coding Standards and Conventions
-
-## Core Sections (Required)
-
-### 1) Naming Conventions
-
-- Files: kebab-case (e.g., `slide-renderer.ts`, `learning-engine.ts`)
-- Variables/Functions: camelCase
-- Constants: UPPER_SNAKE_CASE (e.g., `ELEMENT_TYPES`, `CONFIDENCE_LEVELS`)
-- Types/Interfaces: PascalCase
-
-### 2) Coding Rules
-
-- **No Magic Strings**: Always define constants in `src/types/elements.ts` or `src/types/models.ts`. (from `README.md`)
-- **Consolidate Data**: When adding new element types, define the data interface in `data.ts` and add to `ElementDataMap`. (from `README.md`)
-- **Strict Discriminated Unions**: Do not use `any` for the `data` field in `SlideElement`. (from `README.md`)
-- **Framework Agnostic**: Code must be Vanilla TS without React/Node-specific dependencies. (from `README.md`)
-
-### 3) Evidence
-
-- `README.md`
-- Scan output

package/docs/codebase/INTEGRATIONS.md

@@ -1,12 +0,0 @@
-# Integrations
-
-## Core Sections (Required)
-
-### 1) External Services
-
-- External APIs: NONE (It is a local SDK)
-- Databases: NONE
-
-### 2) Evidence
-
-- `package.json` (no dependencies)

package/docs/codebase/STACK.md

@@ -1,47 +0,0 @@
-# Technology Stack
-
-## Core Sections (Required)
-
-### 1) Runtime Summary
-
-| Area | Value | Evidence |
-|------|-------|----------|
-| Primary language | TypeScript | `package.json`, `tsconfig.json` |
-| Runtime + version | Node.js / Browser (Library) | `package.json` |
-| Package manager | npm | `package-lock.json` |
-| Module/build system | tsup | `package.json` (`scripts.build`) |
-
-### 2) Production Frameworks and Dependencies
-
-List only high-impact production dependencies (frameworks, data, transport, auth).
-
-| Dependency | Version | Role in system | Evidence |
-|------------|---------|----------------|----------|
-| None | N/A | Zero-dependency SDK | `package.json` (no `dependencies`) |
-
-### 3) Development Toolchain
-
-| Tool | Purpose | Evidence |
-|------|---------|----------|
-| `typescript` | Type checking | `package.json` |
-| `tsup` | Module bundler (CJS/ESM) | `package.json` |
-| `vitest` | Unit testing | `package.json` |
-
-### 4) Key Commands
-
-```bash
-npm install
-npm run build
-npm test
-```
-
-### 5) Environment and Config
-
-- Config sources: `tsconfig.json`
-- Required env vars: None detected.
-- Deployment/runtime constraints: Deployed as an npm package via workspace or separate install, exports ESM and CommonJS. Framework-agnostic.
-
-### 6) Evidence
-
-- `package.json`
-- `tsconfig.json`

package/docs/codebase/STRUCTURE.md

@@ -1,41 +0,0 @@
-# Codebase Structure
-
-## Core Sections (Required)
-
-### 1) Top-Level Map
-
-List only meaningful top-level directories and files.
-
-| Path | Purpose | Evidence |
-|------|---------|----------|
-| `src/` | Source code root | Scan output |
-| `src/types/` | Data definitions, Discriminated Unions, and models | `README.md`, Scan output |
-| `src/engines/` | Core logic for game evaluation and spaced repetition | `README.md`, Scan output |
-| `src/renderer/` | Slide rendering and calculation math | `README.md`, Scan output |
-| `src/sync/` | Action manager handling | Scan output |
-| `tests/` | Unit test files | Scan output |
-
-### 2) Entry Points
-
-- Main runtime entry: `src/index.ts`
-- Secondary entry points (worker/cli/jobs): NONE
-- How entry is selected (script/config): Configured in `package.json` (`main`, `module`, `types`, `exports` fields).
-
-### 3) Module Boundaries
-
-| Boundary | What belongs here | What must not be here |
-|----------|-------------------|------------------------|
-| `src/types/` | Interfaces, types, and constants | Business logic, algorithms |
-| `src/engines/` | Pure functions for logic (Game Engine, Learning Engine) | UI rendering code, specific framework APIs |
-
-### 4) Naming and Organization Rules
-
-- File naming pattern: kebab-case (e.g., `game-engine.ts`, `slide-renderer.ts`)
-- Directory organization pattern: domain-based (`engines`, `types`, `renderer`)
-- Import aliasing or path conventions: Relative imports within the SDK, exported centrally via `src/index.ts`.
-
-### 5) Evidence
-
-- `docs/codebase/.codebase-scan.txt`
-- `package.json`
-- `README.md`

package/docs/codebase/TESTING.md

@@ -1,22 +0,0 @@
-# Testing
-
-## Core Sections (Required)
-
-### 1) Testing Frameworks
-
-- Test Runner: `vitest`
-
-### 2) Test Organization
-
-- Location: Tests are colocated in the `tests/` directory at the project root (e.g., `tests/game-engine.test.ts`).
-
-### 3) Key Commands
-
-```bash
-npm test
-```
-
-### 4) Evidence
-
-- `package.json`
-- Scan output

package/src/engines/game-engine.ts

@@ -1,44 +0,0 @@
-import type { GameDataMap } from "../types/data.js";
-import { GAME_TYPES, type GameType } from "../types/elements.js";
-
-/**
- * Validator nhận vào toàn bộ object cấu hình (GameDataMap[T]).
- */
-export const validateGameResult = <T extends GameType>(
-  type: T,
-  userAnswer: any,
-  correctData: GameDataMap[T], // Nhận cả object data thay vì chỉ string
-): boolean => {
-  switch (type) {
-    case GAME_TYPES.QUIZ: {
-      // Ép kiểu về MultipleChoiceData để truy cập correctId
-      const data = correctData as GameDataMap[typeof GAME_TYPES.QUIZ];
-      return userAnswer === data.correctId;
-    }
-
-    case GAME_TYPES.SORTING: {
-      const data = correctData as GameDataMap[typeof GAME_TYPES.SORTING];
-      return JSON.stringify(userAnswer) === JSON.stringify(data.correctOrder);
-    }
-
-    case GAME_TYPES.MATCHING: {
-      const data = correctData as GameDataMap[typeof GAME_TYPES.MATCHING];
-      const userSorted = [...userAnswer].sort();
-      const correctSorted = [...data.correctPairs].sort();
-      return JSON.stringify(userSorted) === JSON.stringify(correctSorted);
-    }
-
-    case GAME_TYPES.HOTSPOT: {
-      const data = correctData as GameDataMap[typeof GAME_TYPES.HOTSPOT];
-      const { x, y } = userAnswer;
-      const zone = data.zones.find((z) => z.id === data.correctZoneId);
-      if (!zone) return false;
-      return (
-        x >= zone.xMin && x <= zone.xMax && y >= zone.yMin && y <= zone.yMax
-      );
-    }
-
-    default:
-      return false;
-  }
-};

package/src/engines/learning-engine.ts

@@ -1,35 +0,0 @@
-import { CONFIDENCE_LEVELS } from "../types/models.js";
-import type { ConfidenceLevel } from "../types/models.js";
-
-/**
- * Tính toán ngày review tiếp theo dựa trên kết quả và độ tự tin.
- * - Đúng + Tự tin Cao: 7 ngày.
- * - Đúng + Tự tin Vừa/Thấp: 1 ngày.
- * - Sai: 0 ngày (ôn lại ngay).
- */
-export const calculateNextReview = (
-  isCorrect: boolean,
-  confidence: ConfidenceLevel,
-): number => {
-  if (!isCorrect) {
-    return 0; // Ôn lại ngay lập tức
-  }
-
-  if (confidence === CONFIDENCE_LEVELS.HIGH) {
-    return 7; // Giãn cách 7 ngày cho câu trả lời tự tin
-  }
-
-  // Trường hợp Medium hoặc Low: Chỉ giãn cách 1 ngày
-  return 1;
-};
-
-/**
- * Điều kiện Mastery (Thành thạo):
- * Chuỗi đúng (streak) >= 3 và lần trả lời gần nhất có độ tự tin Cao.
- */
-export const checkMastery = (
-  streak: number,
-  lastConfidence: ConfidenceLevel,
-): boolean => {
-  return streak >= 3 && lastConfidence === CONFIDENCE_LEVELS.HIGH;
-};

package/src/index.ts

@@ -1,5 +0,0 @@
-import * as SlideRenderer from "./renderer/slide-renderer.js";
-import * as learningEngine from "./engines/learning-engine.js";
-import * as gameEngine from "./engines/game-engine.js";
-export * from "./types/index.js";
-export { SlideRenderer, learningEngine, gameEngine };

package/src/renderer/slide-renderer.ts

@@ -1,27 +0,0 @@
-/**
- * Chuyển đổi tọa độ từ Pixel sang % (Dùng cho Admin Builder)
- * Canvas Builder & Percentage Positioning
- */
-export const calculatePercentPosition = (
-  pixelPos: { left: number; top: number; width: number; height: number },
-  canvasSize: { width: number; height: number },
-) => ({
-  x: (pixelPos.left / canvasSize.width) * 100,
-  y: (pixelPos.top / canvasSize.height) * 100,
-  w: (pixelPos.width / canvasSize.width) * 100,
-  h: (pixelPos.height / canvasSize.height) * 100,
-});
-
-/**
- * Chuyển đổi tọa độ từ % sang Pixel thực tế trên thiết bị.
- * AC 1: Renderer phải tính toán vị trí dựa trên % từ JSON
- */
-export const calculateRealPosition = (
-  percentPos: { x: number; y: number; w: number; h: number },
-  screenSize: { width: number; height: number },
-) => ({
-  left: (percentPos.x * screenSize.width) / 100,
-  top: (percentPos.y * screenSize.height) / 100,
-  width: (percentPos.w * screenSize.width) / 100,
-  height: (percentPos.h * screenSize.height) / 100,
-});

package/src/sync/action-manager.ts

@@ -1,23 +0,0 @@
-import type { ActionLog } from "../index.js";
-
-/**
- * Quản lý hàng đợi hành động để đồng bộ Offline.
- * Cơ chế Action Log (Tránh mất dữ liệu)
- */
-export const filterActionsToSync = (
-  localActions: ActionLog[],
-  lastSyncAtServer: number,
-): ActionLog[] => {
-  // AC 1: Chỉ gửi lên Server những hành động có timestamp lớn hơn thời điểm đồng bộ cuối
-  return localActions.filter((action) => action.timestamp > lastSyncAtServer);
-};
-
-/**
- * Xử lý xung đột theo quy tắc Last Sync Wins.
- */
-export const resolveSyncConflict = (
-  localTimestamp: number,
-  serverTimestamp: number,
-): boolean => {
-  return localTimestamp > serverTimestamp;
-};

package/src/types/actions.ts

@@ -1,83 +0,0 @@
-/**
- * Tập hợp các sự kiện (events) từ người dùng hoặc hệ thống
- * dùng để kích hoạt một hành động (action) nào đó trên Slide.
- */
-export const ACTION_TRIGGERS = {
-  ON_CLICK: "ON_CLICK",
-  ON_DOUBLE_CLICK: "ON_DOUBLE_CLICK",
-  ON_HOVER: "ON_HOVER",
-  ON_ENTER_VIEWPORT: "ON_ENTER_VIEWPORT",
-} as const;
-
-export type ActionTrigger =
-  (typeof ACTION_TRIGGERS)[keyof typeof ACTION_TRIGGERS];
-
-/**
- * Danh sách các loại hành động (side-effects) mà hệ thống hỗ trợ thực thi.
- * Ví dụ: Chuyển trang, ẩn hiện component, phát nhạc, hoặc nộp bài.
- */
-export const ACTION_TYPES = {
-  NAVIGATE_SLIDE: "NAVIGATE_SLIDE",
-  TOGGLE_VISIBILITY: "TOGGLE_VISIBILITY",
-  PLAY_MEDIA: "PLAY_MEDIA",
-  EVALUATE_ANSWER: "EVALUATE_ANSWER",
-} as const;
-
-export type ActionType = (typeof ACTION_TYPES)[keyof typeof ACTION_TYPES];
-
-/**
- * Payload: Dữ liệu cấu hình cho hành động chuyển slide.
- * - `targetSlideId`: ID của slide muốn nhảy tới (Dùng cho điều hướng tự do).
- * - `direction`: Điều hướng tuần tự (Tiến/Lùi).
- */
-export interface NavigatePayload {
-  targetSlideId?: string;
-  direction?: "NEXT" | "PREV";
-}
-
-/**
- * Payload: Dữ liệu cấu hình cho hành động thay đổi trạng thái hiển thị của Element.
- * - `targetElementId`: ID của phần tử bị tác động.
- * - `action`: Trạng thái muốn áp dụng (Hiển thị / Ẩn / Đảo ngược trạng thái).
- */
-export interface ToggleVisibilityPayload {
-  targetElementId: string;
-  action: "SHOW" | "HIDE" | "TOGGLE";
-}
-
-/**
- * Payload: Dữ liệu cấu hình cho hành động chấm điểm và tính toán Spaced Repetition.
- * - `targetElementId`: (Tùy chọn) ID của bài tập (Quiz, Matching,..) cần chấm. Nếu nút bấm nằm rời bên ngoài.
- * - `conceptId`: (Tùy chọn) ID của kỹ năng/khái niệm để lưu tiến độ (mastery) cho học viên.
- */
-export interface EvaluatePayload {
-  targetElementId?: string;
-  conceptId?: string;
-}
-
-/**
- * Từ điển ánh xạ (Mapping Map) cực kỳ quan trọng.
- * Định nghĩa chính xác ActionType nào thì phải xài chung với Payload Interface nào.
- */
-export type ActionPayloadMap = {
-  [ACTION_TYPES.NAVIGATE_SLIDE]: NavigatePayload;
-  [ACTION_TYPES.TOGGLE_VISIBILITY]: ToggleVisibilityPayload;
-  [ACTION_TYPES.PLAY_MEDIA]: { mediaUrl: string; loop: boolean };
-  [ACTION_TYPES.EVALUATE_ANSWER]: EvaluatePayload;
-};
-
-/**
- * Cấu trúc hoàn chỉnh của một Hành động gắn vào Element.
- *
- * @description Sử dụng pattern "Discriminated Union" của TypeScript:
- * Khi dev set thuộc tính `type`, TypeScript sẽ tự động ép buộc `payload`
- * phải chứa các trường dữ liệu tương ứng được định nghĩa trong `ActionPayloadMap`.
- * Tránh tuyệt đối việc râu ông nọ cắm cằm bà kia (VD: type là NAVIGATE nhưng truyền mediaUrl).
- */
-export type ElementAction = {
-  [K in ActionType]: {
-    trigger: ActionTrigger;
-    type: K;
-    payload: ActionPayloadMap[K];
-  };
-}[ActionType];

package/src/types/common.ts

@@ -1,9 +0,0 @@
-/**
- * Cấu trúc tọa độ cơ bản dựa trên tỷ lệ %.
- */
-export interface Position {
-  x: number; // Tọa độ ngang (0-100)
-  y: number; // Tọa độ dọc (0-100)
-  w: number; // Chiều rộng (0-100)
-  h: number; // Chiều cao (0-100)
-}

package/src/types/data.ts

@@ -1,71 +0,0 @@
-// --- Standard Element Data ---
-
-export interface TextData {
-  content: string;
-}
-
-export interface VideoData {
-  src: string;
-  poster?: string;
-  autoPlay?: boolean;
-  muted?: boolean;
-  loop?: boolean;
-  controls?: boolean;
-  isLive?: boolean;
-}
-
-// --- Game Element Data ---
-
-// 1. Multiple Choice: Chọn 1 đáp án đúng
-export interface MultipleChoiceData {
-  question: string;
-  options: { id: string; content: string }[];
-  correctId: string;
-}
-
-// 2. Sorting: Sắp xếp theo thứ tự mảng
-export interface SortingData {
-  items: { id: string; content: string }[];
-  correctOrder: string[]; // Mảng chứa các ID theo thứ tự đúng
-}
-
-// 3. Matching: Nối cặp A - B
-export interface MatchingData {
-  leftColumn: { id: string; content: string }[];
-  rightColumn: { id: string; content: string }[];
-  correctPairs: [string, string][]; // Mảng các cặp [id_trái, id_phải]
-}
-
-// 4. Hotspot: Click vào vùng ảnh
-export interface HotspotData {
-  imageUri: string;
-  zones: {
-    id: string;
-    xMin: number;
-    yMin: number; // Đơn vị %
-    xMax: number;
-    yMax: number;
-  }[];
-  correctZoneId: string;
-}
-
-// --- Data Maps ---
-
-/**
- * Map để liên kết các Game Type với dữ liệu tương ứng.
- */
-export type GameDataMap = {
-  QUIZ: MultipleChoiceData;
-  SORTING: SortingData;
-  MATCHING: MatchingData;
-  HOTSPOT: HotspotData;
-  MEMORY_CARD: any; // Có thể mở rộng thêm sau
-};
-
-/**
- * Map tổng hợp giữa tất cả ElementType và cấu trúc data tương ứng.
- */
-export type ElementDataMap = GameDataMap & {
-  TEXT: TextData;
-  VIDEO: VideoData;
-};

package/src/types/elements.ts

@@ -1,77 +0,0 @@
-import type { ElementAction } from "./actions.js";
-import type { Position } from "./common.js";
-import type { ElementDataMap } from "./data.js";
-
-/**
- * Định nghĩa tất cả các loại phần tử có thể xuất hiện trong một Slide.
- */
-export const ELEMENT_TYPES = {
-  TEXT: "TEXT",
-  VIDEO: "VIDEO",
-  QUIZ: "QUIZ",
-  MATCHING: "MATCHING",
-  SORTING: "SORTING",
-  MEMORY_CARD: "MEMORY_CARD",
-  HOTSPOT: "HOTSPOT",
-} as const;
-
-export type ElementType = (typeof ELEMENT_TYPES)[keyof typeof ELEMENT_TYPES];
-
-/**
- * Định nghĩa các loại game (tập con của ELEMENT_TYPES).
- */
-export const GAME_TYPES = {
-  QUIZ: "QUIZ",
-  MATCHING: "MATCHING",
-  SORTING: "SORTING",
-  MEMORY_CARD: "MEMORY_CARD",
-  HOTSPOT: "HOTSPOT",
-} as const;
-
-export type GameType = Extract<
-  ElementType,
-  (typeof GAME_TYPES)[keyof typeof GAME_TYPES]
->;
-
-/**
- * Định nghĩa style cho một phần tử.
- */
-export interface ElementStyle {
-  backgroundColor?: string;
-  color?: string;
-  fontSize?: number;
-  fontFamily?: string;
-  fontWeight?: string | number;
-  textAlign?: "left" | "center" | "right" | "justify";
-  border?: string;
-  borderRadius?: number;
-  opacity?: number;
-  zIndex?: number;
-  [key: string]: any; // Allow other CSS properties
-}
-/**
- * Định nghĩa các loại animation hỗ trợ
- */
-export interface ElementAnimation {
-  type: "fade-in" | "slide-up" | "bounce" | "zoom-in";
-  duration: number; // Tính bằng ms
-  delay: number; // Độ trễ trước khi chạy (ms)
-  repeat?: boolean;
-}
-
-/**
- * Sử dụng Discriminated Union để đảm bảo type-safety cho thuộc tính 'data'.
- */
-export type SlideElement = {
-  [K in keyof ElementDataMap]: {
-    id: string;
-    type: K;
-    position: Position;
-    style?: ElementStyle;
-    enterAnimation?: ElementAnimation;
-    exitAnimation?: ElementAnimation;
-    actions?: ElementAction[];
-    data: ElementDataMap[K];
-    groupId?: string;
-  };
-}[keyof ElementDataMap];

package/src/types/index.ts

@@ -1,5 +0,0 @@
-export * from "./common.js";
-export * from "./data.js";
-export * from "./elements.js";
-export * from "./models.js";
-export * from "./actions.js";

package/src/types/models.ts

@@ -1,47 +0,0 @@
-import type { SlideElement } from "./elements.js";
-
-// --- Slide Models ---
-
-export interface SlideConfig {
-  aspectRatio: string;
-  theme: string;
-}
-
-export interface Slide {
-  id: string;
-  tenant_id: string;
-  course_id: string;
-  order: number;
-  config?: SlideConfig;
-  elements: SlideElement[];
-}
-
-// --- Tracking & Progress Models ---
-
-export const CONFIDENCE_LEVELS = {
-  HIGH: "High",
-  MEDIUM: "Medium",
-  LOW: "Low",
-} as const;
-
-export type ConfidenceLevel = typeof CONFIDENCE_LEVELS[keyof typeof CONFIDENCE_LEVELS];
-
-export interface ActionLog {
-  action_type: string;
-  timestamp: number;
-  duration: number;
-  result: {
-    is_correct: boolean;
-    confidence: ConfidenceLevel;
-  };
-}
-
-export interface UserProgress {
-  user_id: string;
-  tenant_id: string;
-  concept_id: string;
-  streak: number; // Số lần đúng liên tiếp
-  is_mastered: boolean;
-  next_review_at: string; // ISODate string
-  last_sync_at: string; // ISODate string
-}