broker-core-sdk 1.0.0 → 1.0.1

package/dist/index.cjs

@@ -0,0 +1,157 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  ACTION_TRIGGERS: () => ACTION_TRIGGERS,
+  ACTION_TYPES: () => ACTION_TYPES,
+  CONFIDENCE_LEVELS: () => CONFIDENCE_LEVELS,
+  ELEMENT_TYPES: () => ELEMENT_TYPES,
+  GAME_TYPES: () => GAME_TYPES,
+  SlideRenderer: () => slide_renderer_exports,
+  gameEngine: () => game_engine_exports,
+  learningEngine: () => learning_engine_exports
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/renderer/slide-renderer.ts
+var slide_renderer_exports = {};
+__export(slide_renderer_exports, {
+  calculatePercentPosition: () => calculatePercentPosition,
+  calculateRealPosition: () => calculateRealPosition
+});
+var calculatePercentPosition = (pixelPos, canvasSize) => ({
+  x: pixelPos.left / canvasSize.width * 100,
+  y: pixelPos.top / canvasSize.height * 100,
+  w: pixelPos.width / canvasSize.width * 100,
+  h: pixelPos.height / canvasSize.height * 100
+});
+var calculateRealPosition = (percentPos, screenSize) => ({
+  left: percentPos.x * screenSize.width / 100,
+  top: percentPos.y * screenSize.height / 100,
+  width: percentPos.w * screenSize.width / 100,
+  height: percentPos.h * screenSize.height / 100
+});
+
+// src/engines/learning-engine.ts
+var learning_engine_exports = {};
+__export(learning_engine_exports, {
+  calculateNextReview: () => calculateNextReview,
+  checkMastery: () => checkMastery
+});
+
+// src/types/models.ts
+var CONFIDENCE_LEVELS = {
+  HIGH: "High",
+  MEDIUM: "Medium",
+  LOW: "Low"
+};
+
+// src/engines/learning-engine.ts
+var calculateNextReview = (isCorrect, confidence) => {
+  if (!isCorrect) {
+    return 0;
+  }
+  if (confidence === CONFIDENCE_LEVELS.HIGH) {
+    return 7;
+  }
+  return 1;
+};
+var checkMastery = (streak, lastConfidence) => {
+  return streak >= 3 && lastConfidence === CONFIDENCE_LEVELS.HIGH;
+};
+
+// src/engines/game-engine.ts
+var game_engine_exports = {};
+__export(game_engine_exports, {
+  validateGameResult: () => validateGameResult
+});
+
+// src/types/elements.ts
+var ELEMENT_TYPES = {
+  TEXT: "TEXT",
+  VIDEO: "VIDEO",
+  QUIZ: "QUIZ",
+  MATCHING: "MATCHING",
+  SORTING: "SORTING",
+  MEMORY_CARD: "MEMORY_CARD",
+  HOTSPOT: "HOTSPOT"
+};
+var GAME_TYPES = {
+  QUIZ: "QUIZ",
+  MATCHING: "MATCHING",
+  SORTING: "SORTING",
+  MEMORY_CARD: "MEMORY_CARD",
+  HOTSPOT: "HOTSPOT"
+};
+
+// src/engines/game-engine.ts
+var validateGameResult = (type, userAnswer, correctData) => {
+  switch (type) {
+    case GAME_TYPES.QUIZ: {
+      const data = correctData;
+      return userAnswer === data.correctId;
+    }
+    case GAME_TYPES.SORTING: {
+      const data = correctData;
+      return JSON.stringify(userAnswer) === JSON.stringify(data.correctOrder);
+    }
+    case GAME_TYPES.MATCHING: {
+      const data = correctData;
+      const userSorted = [...userAnswer].sort();
+      const correctSorted = [...data.correctPairs].sort();
+      return JSON.stringify(userSorted) === JSON.stringify(correctSorted);
+    }
+    case GAME_TYPES.HOTSPOT: {
+      const data = correctData;
+      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;
+  }
+};
+
+// src/types/actions.ts
+var ACTION_TRIGGERS = {
+  ON_CLICK: "ON_CLICK",
+  ON_DOUBLE_CLICK: "ON_DOUBLE_CLICK",
+  ON_HOVER: "ON_HOVER",
+  ON_ENTER_VIEWPORT: "ON_ENTER_VIEWPORT"
+};
+var ACTION_TYPES = {
+  NAVIGATE_SLIDE: "NAVIGATE_SLIDE",
+  TOGGLE_VISIBILITY: "TOGGLE_VISIBILITY",
+  PLAY_MEDIA: "PLAY_MEDIA",
+  EVALUATE_ANSWER: "EVALUATE_ANSWER"
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  ACTION_TRIGGERS,
+  ACTION_TYPES,
+  CONFIDENCE_LEVELS,
+  ELEMENT_TYPES,
+  GAME_TYPES,
+  SlideRenderer,
+  gameEngine,
+  learningEngine
+});

package/dist/index.d.cts

@@ -0,0 +1,331 @@
+/**
+ * Chuyển đổi tọa độ từ Pixel sang % (Dùng cho Admin Builder)
+ * Canvas Builder & Percentage Positioning
+ */
+declare const calculatePercentPosition: (pixelPos: {
+    left: number;
+    top: number;
+    width: number;
+    height: number;
+}, canvasSize: {
+    width: number;
+    height: number;
+}) => {
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+};
+/**
+ * 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
+ */
+declare const calculateRealPosition: (percentPos: {
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+}, screenSize: {
+    width: number;
+    height: number;
+}) => {
+    left: number;
+    top: number;
+    width: number;
+    height: number;
+};
+
+declare const slideRenderer_calculatePercentPosition: typeof calculatePercentPosition;
+declare const slideRenderer_calculateRealPosition: typeof calculateRealPosition;
+declare namespace slideRenderer {
+  export { slideRenderer_calculatePercentPosition as calculatePercentPosition, slideRenderer_calculateRealPosition as calculateRealPosition };
+}
+
+/**
+ * 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.
+ */
+declare const ACTION_TRIGGERS: {
+    readonly ON_CLICK: "ON_CLICK";
+    readonly ON_DOUBLE_CLICK: "ON_DOUBLE_CLICK";
+    readonly ON_HOVER: "ON_HOVER";
+    readonly ON_ENTER_VIEWPORT: "ON_ENTER_VIEWPORT";
+};
+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.
+ */
+declare const ACTION_TYPES: {
+    readonly NAVIGATE_SLIDE: "NAVIGATE_SLIDE";
+    readonly TOGGLE_VISIBILITY: "TOGGLE_VISIBILITY";
+    readonly PLAY_MEDIA: "PLAY_MEDIA";
+    readonly EVALUATE_ANSWER: "EVALUATE_ANSWER";
+};
+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).
+ */
+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).
+ */
+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.
+ */
+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.
+ */
+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).
+ */
+type ElementAction = {
+    [K in ActionType]: {
+        trigger: ActionTrigger;
+        type: K;
+        payload: ActionPayloadMap[K];
+    };
+}[ActionType];
+
+/**
+ * Cấu trúc tọa độ cơ bản dựa trên tỷ lệ %.
+ */
+interface Position {
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+}
+
+interface TextData {
+    content: string;
+}
+interface VideoData {
+    src: string;
+    poster?: string;
+    autoPlay?: boolean;
+    muted?: boolean;
+    loop?: boolean;
+    controls?: boolean;
+    isLive?: boolean;
+}
+interface MultipleChoiceData {
+    question: string;
+    options: {
+        id: string;
+        content: string;
+    }[];
+    correctId: string;
+}
+interface SortingData {
+    items: {
+        id: string;
+        content: string;
+    }[];
+    correctOrder: string[];
+}
+interface MatchingData {
+    leftColumn: {
+        id: string;
+        content: string;
+    }[];
+    rightColumn: {
+        id: string;
+        content: string;
+    }[];
+    correctPairs: [string, string][];
+}
+interface HotspotData {
+    imageUri: string;
+    zones: {
+        id: string;
+        xMin: number;
+        yMin: number;
+        xMax: number;
+        yMax: number;
+    }[];
+    correctZoneId: string;
+}
+/**
+ * Map để liên kết các Game Type với dữ liệu tương ứng.
+ */
+type GameDataMap = {
+    QUIZ: MultipleChoiceData;
+    SORTING: SortingData;
+    MATCHING: MatchingData;
+    HOTSPOT: HotspotData;
+    MEMORY_CARD: any;
+};
+/**
+ * Map tổng hợp giữa tất cả ElementType và cấu trúc data tương ứng.
+ */
+type ElementDataMap = GameDataMap & {
+    TEXT: TextData;
+    VIDEO: VideoData;
+};
+
+/**
+ * Định nghĩa tất cả các loại phần tử có thể xuất hiện trong một Slide.
+ */
+declare const ELEMENT_TYPES: {
+    readonly TEXT: "TEXT";
+    readonly VIDEO: "VIDEO";
+    readonly QUIZ: "QUIZ";
+    readonly MATCHING: "MATCHING";
+    readonly SORTING: "SORTING";
+    readonly MEMORY_CARD: "MEMORY_CARD";
+    readonly HOTSPOT: "HOTSPOT";
+};
+type ElementType = (typeof ELEMENT_TYPES)[keyof typeof ELEMENT_TYPES];
+/**
+ * Định nghĩa các loại game (tập con của ELEMENT_TYPES).
+ */
+declare const GAME_TYPES: {
+    readonly QUIZ: "QUIZ";
+    readonly MATCHING: "MATCHING";
+    readonly SORTING: "SORTING";
+    readonly MEMORY_CARD: "MEMORY_CARD";
+    readonly HOTSPOT: "HOTSPOT";
+};
+type GameType = Extract<ElementType, (typeof GAME_TYPES)[keyof typeof GAME_TYPES]>;
+/**
+ * Định nghĩa style cho một phần tử.
+ */
+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;
+}
+/**
+ * Định nghĩa các loại animation hỗ trợ
+ */
+interface ElementAnimation {
+    type: "fade-in" | "slide-up" | "bounce" | "zoom-in";
+    duration: number;
+    delay: number;
+    repeat?: boolean;
+}
+/**
+ * Sử dụng Discriminated Union để đảm bảo type-safety cho thuộc tính 'data'.
+ */
+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];
+
+interface SlideConfig {
+    aspectRatio: string;
+    theme: string;
+}
+interface Slide {
+    id: string;
+    tenant_id: string;
+    course_id: string;
+    order: number;
+    config?: SlideConfig;
+    elements: SlideElement[];
+}
+declare const CONFIDENCE_LEVELS: {
+    readonly HIGH: "High";
+    readonly MEDIUM: "Medium";
+    readonly LOW: "Low";
+};
+type ConfidenceLevel = typeof CONFIDENCE_LEVELS[keyof typeof CONFIDENCE_LEVELS];
+interface ActionLog {
+    action_type: string;
+    timestamp: number;
+    duration: number;
+    result: {
+        is_correct: boolean;
+        confidence: ConfidenceLevel;
+    };
+}
+interface UserProgress {
+    user_id: string;
+    tenant_id: string;
+    concept_id: string;
+    streak: number;
+    is_mastered: boolean;
+    next_review_at: string;
+    last_sync_at: string;
+}
+
+/**
+ * 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).
+ */
+declare const calculateNextReview: (isCorrect: boolean, confidence: ConfidenceLevel) => number;
+/**
+ * Đ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.
+ */
+declare const checkMastery: (streak: number, lastConfidence: ConfidenceLevel) => boolean;
+
+declare const learningEngine_calculateNextReview: typeof calculateNextReview;
+declare const learningEngine_checkMastery: typeof checkMastery;
+declare namespace learningEngine {
+  export { learningEngine_calculateNextReview as calculateNextReview, learningEngine_checkMastery as checkMastery };
+}
+
+/**
+ * Validator nhận vào toàn bộ object cấu hình (GameDataMap[T]).
+ */
+declare const validateGameResult: <T extends GameType>(type: T, userAnswer: any, correctData: GameDataMap[T]) => boolean;
+
+declare const gameEngine_validateGameResult: typeof validateGameResult;
+declare namespace gameEngine {
+  export { gameEngine_validateGameResult as validateGameResult };
+}
+
+export { ACTION_TRIGGERS, ACTION_TYPES, type ActionLog, type ActionPayloadMap, type ActionTrigger, type ActionType, CONFIDENCE_LEVELS, type ConfidenceLevel, ELEMENT_TYPES, type ElementAction, type ElementAnimation, type ElementDataMap, type ElementStyle, type ElementType, type EvaluatePayload, GAME_TYPES, type GameDataMap, type GameType, type HotspotData, type MatchingData, type MultipleChoiceData, type NavigatePayload, type Position, type Slide, type SlideConfig, type SlideElement, slideRenderer as SlideRenderer, type SortingData, type TextData, type ToggleVisibilityPayload, type UserProgress, type VideoData, gameEngine, learningEngine };