@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).

Package ini cocok untuk worker/background job/service sync, bukan untuk forwarding token user.

Flow

Backend Modul / Worker / Cron
  -> Gateway:3000/api/students
     X-App-ID: <id>
     X-App-Secret: <secret>
     X-School-ID: <school-id>
  -> Gateway forward ke be-loka-core:3002/api/v1/students
  -> Core ServiceAuthGuard validasi credentials

Semua request tetap lewat Gateway, bukan langsung ke Core.

Install

npm install @loka-sms/core-integration-be

Environment Variable

| 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) |

Contoh .env:

CORE_SERVICE_URL=http://localhost:3000/api
CORE_APP_ID=erapor-app
CORE_APP_SECRET=erapor-secret

URL Gateway

| Lingkungan | CORE_SERVICE_URL | |---|---| | Lokal (backend di host) | http://localhost:3000/api | | Docker compose | http://be-loka-gateway:3000/api | | Production | <gateway-url>/api (dari environment variable production) |

Catatan: Jangan tambah /api/v1 di URL jika lewat Gateway. Gateway sudah rewrite /api ke /api/v1 secara otomatis.

Setup AppModule

import { Module } from '@nestjs/common';
import { ConfigModule } from '@nestjs/config';
import { CoreIntegrationModule } from '@loka-sms/core-integration-be';

@Module({
  imports: [
    ConfigModule.forRoot({ isGlobal: true }),
    CoreIntegrationModule,
  ],
})
export class AppModule {}

Atau dengan konfigurasi eksplisit:

CoreIntegrationModule.forRoot({
  baseUrl: 'http://localhost:3000/api',
  appId: 'erapor-app',
  appSecret: 'erapor-secret',
  timeout: 10000,
})

Cara Pakai

import { Injectable } from '@nestjs/common';
import { CoreIntegrationService } from '@loka-sms/core-integration-be';

@Injectable()
export class RaporSyncService {
  constructor(private readonly core: CoreIntegrationService) {}

  async generate(schoolId: string) {
    const students = await this.core.getStudents(schoolId, { status: 'active' });
    const classes = await this.core.getClasses(schoolId, { grade: 7 });
    return { students, classes };
  }
}

Package selalu mengirim X-App-ID, X-App-Secret, dan X-School-ID. Tidak perlu panggil method khusus untuk set auth.

Method Tersedia

| Method | Core Endpoint via Gateway | |---|---| | getStudents(schoolId, params) | GET /api/students | | getStudentsByClass(classId, schoolId) | GET /api/students?class_id=...&status=active | | getStudent(studentId, schoolId) | GET /api/students/:id | | 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, params) | GET /api/classes | | getSubjects(schoolId, params) | GET /api/subjects | | getCurriculums(schoolId, params) | GET /api/curriculum | | getAcademicCalendar(schoolId, params) | GET /api/academic-calendar | | getRooms(schoolId, params) | GET /api/rooms | | getKKM(subjectId, gradeLevel, schoolId) | GET /api/kkm | | pushGradeToCore(schoolId, gradeData) | POST /api/grades/sync | | createNotification(schoolId, payload) | POST /api/notifications |

Generic Request

Kalau method wrapper belum tersedia:

const data = await this.core.get('teaching-schedule', schoolId, {
  params: { class_id: classId },
});

await this.core.post('notifications', schoolId, {
  user_id: 'user_xxx',
  type: 'rapor_ready',
  title: 'Rapor siap dicek',
  message: 'Nilai akhir sudah siap.',
});

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:

this.core.get('students', schoolId)

Salah:

this.core.get('api/students', schoolId)
this.core.get('api/v1/students', schoolId)

Data Per Modul

| Modul | Ambil Dari Core | Jangan Ambil Dari Core | |---|---|---| | LMS | siswa, guru, kelas, mapel, KKM, kalender | nilai berjalan (milik LMS) | | E-Rapor | siswa, kelas, guru, mapel, kurikulum, KKM, semester | nilai mentah tugas/ujian; ambil nilai final dari LMS | | Presensi | siswa, kelas, guru, kalender, jadwal | hasil presensi operasional | | Keuangan | siswa, orang tua, kelas | transaksi, invoice, pembayaran | | PPDB | referensi sekolah | data pendaftar sebelum resmi jadi siswa | | HRIS | guru, staff, struktur sekolah | payroll, cuti, KPI internal |

Prasyarat Core

Setiap APP_ID harus terdaftar di tabel loka_sms.applications dengan secret di-hash bcrypt.

Contoh registrasi:

INSERT INTO loka_sms.applications (app_id, app_secret, name, service_url, status)
VALUES ('erapor-app', '<bcrypt-hash-dari-erapor-secret>', 'E-Rapor Service', 'http://erapor:3012', 'active');

Endpoint Core yang akan dipanggil juga harus memiliki decorator @AllowServiceAuth(). Sebagian besar endpoint sudah.

Troubleshooting

Error: CoreIntegrationModule requires baseUrl or CORE_SERVICE_URL

Set env:

CORE_SERVICE_URL=http://localhost:3000/api

Error: CoreIntegrationModule requires appId or CORE_APP_ID, APP_ID

Set env:

CORE_APP_ID=erapor-app
CORE_APP_SECRET=erapor-secret

Error 401 / 403 dari Core

Cek:

• APP_ID dan APP_SECRET sudah terdaftar di tabel loka_sms.applications
• Secret di database adalah bcrypt hash
• Endpoint Core memiliki @AllowServiceAuth()
• Status aplikasi di database adalah active

Error 404

Cek path. Jangan tambah /api atau /api/v1 di method.

Data kosong

Cek schoolId yang dikirim. Pastikan X-School-ID benar.

Catatan

• Package ini untuk service-to-service / worker mode (tanpa user JWT).
• Semua request lewat Gateway, bukan langsung ke Core.
• Endpoint Core tetap melakukan validasi credentials dan permission.
• Untuk menambah APP_ID baru, tim Core harus insert record di tabel applications dengan secret bcrypt.