@loka-sms/core-integration-be 0.0.1 → 0.0.3

package/README.md

@@ -1,6 +1,6 @@
-# @loka-sms/core-integration-be
+# @loka-sms/core-integration-be
 
-NestJS helper package untuk backend modul Loka SMS yang perlu mengakses data Core via service-to-service auth (`X-App-ID` + `X-App-Secret`).
+NestJS helper package untuk backend modul OMNISCHOOL yang perlu mengakses data Core via service-to-service auth (`X-App-ID` + `X-App-Secret`).
 
 Package ini cocok untuk **worker/background job/service sync**, bukan untuk forwarding token user.
 
@@ -28,9 +28,9 @@ npm install @loka-sms/core-integration-be
 
 | Variabel | Wajib | Fallback | Keterangan |
 |---|---|---|---|
-| `CORE_SERVICE_URL` | ✅ | — | Base URL Gateway, contoh: `http://localhost:3000/api` |
-| `CORE_APP_ID` | ✅ | `APP_ID` | Application ID yang terdaftar di Core |
-| `CORE_APP_SECRET` | ✅ | `APP_SECRET` | Application secret (plain, bukan bcrypt) |
+| `CORE_SERVICE_URL` | ✅ | — | Base URL Gateway, contoh: `http://localhost:3000/api` |
+| `CORE_APP_ID` | ✅ | `APP_ID` | Application ID yang terdaftar di Core |
+| `CORE_APP_SECRET` | ✅ | `APP_SECRET` | Application secret (plain, bukan bcrypt) |
 
 Contoh `.env`:
 
@@ -89,7 +89,7 @@ export class RaporSyncService {
 
   async generate(schoolId: string) {
     const students = await this.core.getStudents(schoolId, { status: 'active' });
-    const classes = await this.core.getClasses(schoolId);
+    const classes = await this.core.getClasses(schoolId, { grade: 7 });
     return { students, classes };
   }
 }
@@ -107,10 +107,12 @@ Package selalu mengirim `X-App-ID`, `X-App-Secret`, dan `X-School-ID`. Tidak per
 | `findStudentByEmail(email, schoolId)` | `GET /api/students?q=...&limit=1` |
 | `getParentChildrenByUserId(parentUserId, schoolId)` | `GET /api/parents/by-user/:id/children` |
 | `getParentChildIdsByUserId(parentUserId, schoolId)` | `GET /api/parents/by-user/:id/children` |
+| `getParentChildUserIdsByUserId(parentUserId, schoolId)` | `GET /api/parents/by-user/:id/children` |
 | `resolveParentStudentScope(parentUserId, schoolId, requestedStudentId?)` | `GET /api/parents/by-user/:id/children` |
+| `resolveParentStudentUserScope(parentUserId, schoolId, requestedStudentUserId?)` | `GET /api/parents/by-user/:id/children` |
 | `getTeachers(schoolId)` | `GET /api/teachers` |
 | `getTeacher(teacherId, schoolId)` | `GET /api/teachers/:id` |
-| `getClasses(schoolId)` | `GET /api/classes` |
+| `getClasses(schoolId, params)` | `GET /api/classes` |
 | `getSubjects(schoolId, params)` | `GET /api/subjects` |
 | `getCurriculums(schoolId, params)` | `GET /api/curriculum` |
 | `getAcademicCalendar(schoolId, params)` | `GET /api/academic-calendar` |
@@ -138,6 +140,12 @@ await this.core.post('notifications', schoolId, {
 
 Path tidak perlu diawali `/api` atau `/api/v1`.
 
+## Catatan Identity Siswa
+
+- `getParentChildIdsByUserId()` dan `resolveParentStudentScope()` mengembalikan **Core student profile id** (`students.id`).
+- `getParentChildUserIdsByUserId()` dan `resolveParentStudentUserScope()` mengembalikan **Core user id siswa** (`students.user_id` / `userId`). Gunakan ini untuk modul yang menyimpan relasi berdasarkan user id, misalnya LMS enrollment `studentUserId`.
+- `getClasses(schoolId, params)` mendukung filter Core seperti `{ grade: 7, academic_year: '2025/2026' }`.
+
 Benar:
 ```ts
 this.core.get('students', schoolId)

package/dist/core-integration.service.d.ts

@@ -14,6 +14,12 @@ export declare class CoreIntegrationService {
     private getHeaders;
     private makeUrl;
     private extractStudentId;
+    private extractStudentUserId;
+    private unwrapRecord;
+    private extractUserId;
+    private extractEntityId;
+    private matchByUserId;
+    private assertTenantScope;
     get<T = any>(path: string, schoolId?: string, options?: CoreRequestOptions): Promise<T>;
     post<T = any>(path: string, schoolId: string | undefined, body?: unknown, options?: CoreRequestOptions): Promise<T>;
     put<T = any>(path: string, schoolId: string | undefined, body?: unknown, options?: CoreRequestOptions): Promise<T>;
@@ -21,15 +27,38 @@ export declare class CoreIntegrationService {
     delete<T = any>(path: string, schoolId?: string, options?: CoreRequestOptions): Promise<T>;
     getParentChildrenByUserId(parentUserId: string, schoolId: string): Promise<any[]>;
     getParentChildIdsByUserId(parentUserId: string, schoolId: string): Promise<string[]>;
+    getParentChildUserIdsByUserId(parentUserId: string, schoolId: string): Promise<string[]>;
+    resolveParentStudentUserScope(parentUserId: string, schoolId: string, requestedStudentUserId?: string): Promise<string[]>;
     resolveParentStudentScope(parentUserId: string, schoolId: string, requestedStudentId?: string): Promise<string[]>;
     getStudents(schoolId: string, params?: Record<string, unknown>): Promise<any[]>;
     getStudentsByClass(classId: string, schoolId: string): Promise<any[]>;
+    getUser(userId: string, schoolId: string): Promise<any>;
     getStudent(studentId: string, schoolId: string): Promise<any>;
+    getStudentByUserId(userId: string, schoolId: string): Promise<any>;
+    resolveStudentUserIdToStudentId(userId: string, schoolId: string): Promise<string | null>;
     findStudentByEmail(email: string, schoolId: string): Promise<any>;
     getTeacher(teacherId: string, schoolId: string): Promise<any>;
-    getClasses(schoolId: string): Promise<any[]>;
+    getTeacherByUserId(userId: string, schoolId: string): Promise<any>;
+    resolveTeacherUserIdToTeacherId(userId: string, schoolId: string): Promise<string | null>;
+    reconcileAcademicData(schoolId: string, academicYear?: string): Promise<{
+        teachers: any[];
+        classes: any[];
+        assignments: any[];
+    }>;
+    getTeacherAssignments(teacherId: string, schoolId: string, academicYear?: string): Promise<any[]>;
+    getClass(classId: string, schoolId: string): Promise<any>;
+    getClasses(schoolId: string, params?: Record<string, unknown>): Promise<any[]>;
     getTeachers(schoolId: string): Promise<any[]>;
     getSubjects(schoolId: string, params?: Record<string, unknown>): Promise<any[]>;
+    getSubject(subjectId: string, schoolId: string): Promise<any>;
+    getRoom(roomId: string, schoolId: string): Promise<any>;
+    getTimeSlots(schoolId: string): Promise<any[]>;
+    getActiveAcademicYear(schoolId: string): Promise<any | null>;
+    getActiveSemester(schoolId: string): Promise<any | null>;
+    getAcademicYear(yearId: string, schoolId: string): Promise<any | null>;
+    getSemester(semesterId: string, schoolId: string): Promise<any | null>;
+    getTeachingSchedule(scheduleId: string, schoolId: string): Promise<any | null>;
+    findTeachingSchedules(schoolId: string, params?: Record<string, unknown>): Promise<any[]>;
     getCurriculums(schoolId: string, params?: Record<string, unknown>): Promise<any[]>;
     getAcademicCalendar(schoolId: string, params?: Record<string, unknown>): Promise<any[]>;
     getRooms(schoolId: string, params?: Record<string, unknown>): Promise<any[]>;

package/dist/core-integration.service.js

@@ -59,6 +59,34 @@ let CoreIntegrationService = CoreIntegrationService_1 = class CoreIntegrationSer
     extractStudentId(child) {
         return child?.student_id || child?.student?.id || child?.studentUserId || child?.id || null;
     }
+    extractStudentUserId(child) {
+        return child?.student_user_id || child?.studentUserId || child?.student?.userId || child?.student?.user_id || child?.student?.user?.id || child?.userId || child?.user_id || null;
+    }
+    unwrapRecord(data) {
+        return data?.data || data;
+    }
+    extractUserId(entity) {
+        return entity?.userId || entity?.user_id || entity?.user?.id || null;
+    }
+    extractEntityId(entity) {
+        return entity?.id || null;
+    }
+    matchByUserId(items, userId) {
+        for (const item of items) {
+            if (item?.userId === userId)
+                return item;
+            if (item?.user_id === userId)
+                return item;
+            if (item?.user?.id === userId)
+                return item;
+        }
+        return null;
+    }
+    assertTenantScope(schoolId, contextLabel) {
+        if (!schoolId) {
+            throw new Error(`${contextLabel}: schoolId (X-School-ID) is required for non-super_admin operations`);
+        }
+    }
     async get(path, schoolId, options = {}) {
         const { headers, ...requestOptions } = options;
         const res = await (0, rxjs_1.firstValueFrom)(this.httpService.get(this.makeUrl(path), {
@@ -118,6 +146,25 @@ let CoreIntegrationService = CoreIntegrationService_1 = class CoreIntegrationSer
             .map((child) => this.extractStudentId(child))
             .filter((studentId) => !!studentId);
     }
+    async getParentChildUserIdsByUserId(parentUserId, schoolId) {
+        const children = await this.getParentChildrenByUserId(parentUserId, schoolId);
+        return children
+            .map((child) => this.extractStudentUserId(child))
+            .filter((studentUserId) => !!studentUserId);
+    }
+    async resolveParentStudentUserScope(parentUserId, schoolId, requestedStudentUserId) {
+        const childUserIds = await this.getParentChildUserIdsByUserId(parentUserId, schoolId);
+        if (childUserIds.length === 0) {
+            throw new common_1.ForbiddenException('Parent has no linked children with user accounts in this school');
+        }
+        if (!requestedStudentUserId) {
+            return childUserIds;
+        }
+        if (!childUserIds.includes(requestedStudentUserId)) {
+            throw new common_1.ForbiddenException('Child user is not linked to this parent');
+        }
+        return [requestedStudentUserId];
+    }
     async resolveParentStudentScope(parentUserId, schoolId, requestedStudentId) {
         const childIds = await this.getParentChildIdsByUserId(parentUserId, schoolId);
         if (childIds.length === 0) {
@@ -134,7 +181,8 @@ let CoreIntegrationService = CoreIntegrationService_1 = class CoreIntegrationSer
     async getStudents(schoolId, params = {}) {
         try {
             const data = await this.get('students', schoolId, { params });
-            return data?.data || data?.students || data || [];
+            const body = data?.data || data || {};
+            return body?.data || body?.students || body || [];
         }
         catch (error) {
             if (error.response?.status === 404) {
@@ -147,15 +195,37 @@ let CoreIntegrationService = CoreIntegrationService_1 = class CoreIntegrationSer
     async getStudentsByClass(classId, schoolId) {
         return this.getStudents(schoolId, { class_id: classId, status: 'active' });
     }
+    async getUser(userId, schoolId) {
+        try {
+            return this.unwrapRecord(await this.get(`users/${userId}`, schoolId));
+        }
+        catch (error) {
+            this.logger.warn(`Failed to fetch user ${userId}: ${error.message}`);
+            return null;
+        }
+    }
     async getStudent(studentId, schoolId) {
         try {
-            return await this.get(`students/${studentId}`, schoolId);
+            return this.unwrapRecord(await this.get(`students/${studentId}`, schoolId));
         }
         catch (error) {
             this.logger.warn(`Failed to fetch student ${studentId}: ${error.message}`);
             return null;
         }
     }
+    async getStudentByUserId(userId, schoolId) {
+        try {
+            return this.unwrapRecord(await this.get(`students/by-user/${userId}`, schoolId));
+        }
+        catch (error) {
+            this.logger.warn(`Failed to fetch student by user ${userId}: ${error.message}`);
+            return null;
+        }
+    }
+    async resolveStudentUserIdToStudentId(userId, schoolId) {
+        const student = await this.getStudentByUserId(userId, schoolId);
+        return student?.id || null;
+    }
     async findStudentByEmail(email, schoolId) {
         try {
             const data = await this.get('students', schoolId, { params: { q: email, limit: 1 } });
@@ -177,10 +247,71 @@ let CoreIntegrationService = CoreIntegrationService_1 = class CoreIntegrationSer
             return null;
         }
     }
-    async getClasses(schoolId) {
+    async getTeacherByUserId(userId, schoolId) {
+        // Fast path: try direct lookup endpoint (if Core provides it)
         try {
-            const data = await this.get('classes', schoolId);
-            return data?.data || data || [];
+            const data = await this.get(`teachers/by-user/${userId}`, schoolId);
+            return this.unwrapRecord(data);
+        }
+        catch {
+            // Fallback: fetch all active teachers and find match by userId
+            try {
+                const teachers = await this.getTeachers(schoolId);
+                return this.matchByUserId(teachers, userId);
+            }
+            catch {
+                return null;
+            }
+        }
+    }
+    async resolveTeacherUserIdToTeacherId(userId, schoolId) {
+        const teacher = await this.getTeacherByUserId(userId, schoolId);
+        return this.extractEntityId(teacher);
+    }
+    async reconcileAcademicData(schoolId, academicYear) {
+        try {
+            const data = await this.post('integrations/lms/reconcile', schoolId, {
+                schoolId,
+                academicYear,
+            });
+            const body = data?.data || data;
+            return {
+                teachers: body?.teachers || [],
+                classes: body?.classes || [],
+                assignments: body?.assignments || [],
+            };
+        }
+        catch (error) {
+            this.logger.error(`Failed to reconcile academic data: ${error.message}`);
+            throw new Error('Core service unavailable: unable to reconcile academic data');
+        }
+    }
+    async getTeacherAssignments(teacherId, schoolId, academicYear) {
+        try {
+            const data = await this.get(`teachers/${teacherId}/assignments`, schoolId, {
+                params: academicYear ? { academicYear } : {},
+            });
+            const raw = data?.data || data;
+            return raw?.data || (Array.isArray(raw) ? raw : []);
+        }
+        catch {
+            return [];
+        }
+    }
+    async getClass(classId, schoolId) {
+        try {
+            return this.unwrapRecord(await this.get(`classes/${classId}`, schoolId));
+        }
+        catch (error) {
+            this.logger.warn(`Failed to fetch class ${classId}: ${error.message}`);
+            return null;
+        }
+    }
+    async getClasses(schoolId, params = {}) {
+        try {
+            const data = await this.get('classes', schoolId, { params });
+            const body = data?.data || data || {};
+            return body?.data || body || [];
         }
         catch (error) {
             this.logger.error(`Failed to fetch classes: ${error.message}`);
@@ -200,7 +331,91 @@ let CoreIntegrationService = CoreIntegrationService_1 = class CoreIntegrationSer
     }
     async getSubjects(schoolId, params = {}) {
         const data = await this.get('subjects', schoolId, { params });
-        return data?.data || data || [];
+        const body = data?.data || data || {};
+        return body?.data || body || [];
+    }
+    async getSubject(subjectId, schoolId) {
+        try {
+            return this.unwrapRecord(await this.get(`subjects/${subjectId}`, schoolId));
+        }
+        catch (error) {
+            this.logger.warn(`Failed to fetch subject ${subjectId}: ${error.message}`);
+            return null;
+        }
+    }
+    async getRoom(roomId, schoolId) {
+        try {
+            return this.unwrapRecord(await this.get(`rooms/${roomId}`, schoolId));
+        }
+        catch (error) {
+            this.logger.warn(`Failed to fetch room ${roomId}: ${error.message}`);
+            return null;
+        }
+    }
+    async getTimeSlots(schoolId) {
+        try {
+            const data = await this.get('time-slots', schoolId);
+            return data?.data || data || [];
+        }
+        catch (error) {
+            this.logger.warn(`Failed to fetch time slots: ${error.message}`);
+            return [];
+        }
+    }
+    async getActiveAcademicYear(schoolId) {
+        try {
+            return this.unwrapRecord(await this.get('academic-years/active', schoolId));
+        }
+        catch (error) {
+            this.logger.warn(`Failed to fetch active academic year: ${error.message}`);
+            return null;
+        }
+    }
+    async getActiveSemester(schoolId) {
+        try {
+            return this.unwrapRecord(await this.get('academic-years/active-semester', schoolId));
+        }
+        catch (error) {
+            this.logger.warn(`Failed to fetch active semester: ${error.message}`);
+            return null;
+        }
+    }
+    async getAcademicYear(yearId, schoolId) {
+        try {
+            return this.unwrapRecord(await this.get(`academic-years/${yearId}`, schoolId));
+        }
+        catch (error) {
+            this.logger.warn(`Failed to fetch academic year ${yearId}: ${error.message}`);
+            return null;
+        }
+    }
+    async getSemester(semesterId, schoolId) {
+        try {
+            return this.unwrapRecord(await this.get(`academic-years/semesters/${semesterId}`, schoolId));
+        }
+        catch (error) {
+            this.logger.warn(`Failed to fetch semester ${semesterId}: ${error.message}`);
+            return null;
+        }
+    }
+    async getTeachingSchedule(scheduleId, schoolId) {
+        try {
+            return this.unwrapRecord(await this.get(`teaching-schedules/${scheduleId}`, schoolId));
+        }
+        catch (error) {
+            this.logger.warn(`Failed to fetch teaching schedule ${scheduleId}: ${error.message}`);
+            return null;
+        }
+    }
+    async findTeachingSchedules(schoolId, params = {}) {
+        try {
+            const data = await this.get('teaching-schedules', schoolId, { params });
+            return data?.data || data || [];
+        }
+        catch (error) {
+            this.logger.warn(`Failed to fetch teaching schedules: ${error.message}`);
+            return [];
+        }
     }
     async getCurriculums(schoolId, params = {}) {
         const data = await this.get('curriculum', schoolId, { params });

package/package.json

@@ -1,7 +1,7 @@
-{
+{
   "name": "@loka-sms/core-integration-be",
-  "version": "0.0.1",
-  "description": "Internal NestJS client for service-to-service access to Loka SMS Core APIs",
+  "version": "0.0.3",
+  "description": "Internal NestJS client for service-to-service access to OMNISCHOOL Core APIs",
   "license": "MIT",
   "type": "commonjs",
   "main": "dist/index.js",