@bumiresourcesminerals/approval-easy-connect

Library untuk integrasi ke Approval System internal BRM.

Package ini biasanya dipakai untuk:

• validasi token Microsoft Graph
• ambil session user dari Approval System
• cek permission menu admin
• create approval transaction dari aplikasi lain
• ambil detail/status approval
• generate record ID yang sinkron dengan Approval System

Install

npm install @bumiresourcesminerals/approval-easy-connect

Environment Variable

MSGRAPH_ENDPOINT=https://graph.microsoft.com/v1.0/me/
APPROVAL_SYSTEM_ENDPOINT=https://approval-system-host

Quick Start

Contoh seperti pola di FARMS-SAP:

const express = require("express");
const ApprovalSystemAPI = require("@bumiresourcesminerals/approval-easy-connect");

const app = express();

app.use(express.json());
app.use(ApprovalSystemAPI.authenticateToken);

app.get("/api/example", async (req, res) => {
  const api = new ApprovalSystemAPI(req.token);

  return res.json({
    employee_id: req.userInfo.employee_id,
    fullname: req.userInfo.fullname,
    business_entity: req.userInfo.business_entity,
    permissions: req.userInfo.access_permission,
  });
});

Setelah authenticateToken berhasil, object berikut tersedia:

• req.token
• req.email
• req.userInfo

req.userInfo berasal dari endpoint /api/signin Approval System.

Permission Middleware

Contoh route admin:

const ApprovalSystemAPI = require("@bumiresourcesminerals/approval-easy-connect");

const api = new ApprovalSystemAPI();
const menu = "CR";

app.get(
  "/api/capex/admin",
  api.adminCheckPermission(menu, "READ"),
  controller.History
);

Rule permission saat ini:

• READ menerima user dengan permission READ atau WRITE
• WRITE hanya menerima user dengan permission WRITE

Jadi kalau endpoint hanya baca data, pakai:

api.adminCheckPermission(menu, "READ")

Kalau endpoint mutasi data, pakai:

api.adminCheckPermission(menu, "WRITE")

Contoh Penggunaan Seperti SAP

Contoh create record + create approval seperti di FARMS-SAP:

const ApprovalSystemAPI = require("@bumiresourcesminerals/approval-easy-connect");

async function createProduct(req, Product, session) {
  const api = new ApprovalSystemAPI(req.token);
  const userInfo = req.userInfo;

  const recordId = await api.GetRecordId({
    model: Product,
    type_record: "FRM",
    business_code: userInfo.business_entity,
    department: "ICT",
    document_name: "SAPPRD",
    column_name: "record_id",
    session,
    maxAttempts: 20,
  });

  await api.createApproval({
    form_code: "SAPPRD",
    form_submit_id: recordId,
    created_by: userInfo.employee_id,
    custom_approval: [],
    notification: {
      description: "SAP Product Upload",
    },
  });

  return recordId;
}

Contoh ambil detail/status approval:

const api = new ApprovalSystemAPI(req.token);

const detail = await api.getApprovalDetail(recordId);
const status = await api.getApprovalStatus(recordId);

API Reference

new ApprovalSystemAPI(token)

Membuat instance API client.

Parameter:

• token: string Token bearer Microsoft Graph yang juga dikirim ke Approval System lewat header x-access-token.

ApprovalSystemAPI.authenticateToken(req, res, next)

Middleware auth.

Perilaku:

• baca header x-access-token
• call MSGRAPH_ENDPOINT
• call /api/signin ke Approval System
• simpan hasil ke req.userInfo

api.adminCheckPermission(menu, typePermission)

Middleware permission untuk route admin.

Parameter:

• menu: string Kode menu approval, contoh: CR, TA, SAPPRD
• typePermission: string Nilai yang didukung: READ atau WRITE

api.createApproval(data)

POST ke /api/approval.

Parameter:

• data: object

Payload minimum yang umum dipakai:

• form_code: string
• form_submit_id: string
• custom_approval: string[]
• notification: object

Field lain boleh ikut dikirim sesuai kontrak Approval System yang dipakai aplikasi Anda.

api.broadcastwa(data)

POST ke /api/broadcastwa.

Parameter:

• data: object

Umumnya berisi payload broadcast WhatsApp personal.

api.broadcastwaGroup(data)

POST ke /api/broadcastwa/group.

Parameter:

• data: object

Umumnya berisi payload broadcast WhatsApp group.

api.saveRequestLog(data)

POST ke /api/requestlog.

Parameter:

• data: object

Field yang biasa dipakai:

• time_request: Date|string
• ip: string
• os: string
• browser: string
• method: string
• url: string
• nik: string
• email: string
• appName: string
• page: string

api.getBaseUrl(data)

GET ke /api/baseurl.

Parameter:

• data: object

Query parameter diteruskan apa adanya ke Approval System.

api.rollbackCreateApproval(data)

POST ke /api/approval/rollback.

Parameter:

• data: object

Field minimum:

• record_id: string

api.getApprovalDetail(recordId)

GET ke /api/approval/:recordId.

Parameter:

• recordId: string

api.getApprovalStatus(recordId)

GET ke /api/approval-status/:recordId.

Parameter:

• recordId: string

api.getUserByEmployeeId(employeeId)

GET ke /api/user/employeeid/:employeeId.

Parameter:

• employeeId: string

api.getUserByIdRow(id)

GET ke /api/user/idrow/:id.

Parameter:

• id: string

api.getUserByEmail(email)

GET ke /api/user/email/:email.

Parameter:

• email: string

api.getUserByBranch(branchids)

GET ke /api/user/branchid/:branchids.

Parameter:

• branchids: string

api.getUserByJobPosition(id)

GET ke /api/user/jobposition/:id.

Parameter:

• id: string

api.signIn()

POST ke /api/signin.

Tidak butuh parameter tambahan selain token pada constructor.

api.getOrganization(branchId = null)

GET ke /api/organizations atau /api/organizations/:branchId.

Parameter:

• branchId?: string|null

api.setRequestorDetail(employee_id, object)

Helper untuk inject hasil getUserByEmployeeId() ke object target.

Parameter:

• employee_id: string
• object: object

Output:

• menambahkan object.requestor_id

api.setApprovalProcess(recordId, object)

Helper untuk inject hasil getApprovalDetail() ke object target.

Parameter:

• recordId: string
• object: object

Output:

• menambahkan object.approval_process_id

api.GetRecordId(data)

Generate record ID baru dan cross-check ke Approval System agar tidak bentrok.

Parameter:

• data.model: mongoose model
• data.type_record: string
• data.business_code: string
• data.department: string
• data.document_name: string
• data.column_name: string
• data.session: mongoose session
• data.maxAttempts?: number

Format record ID yang dihasilkan:

{business_code}-{department}-{type_record}-{document_name}{YYMM}{NNNN}

Contoh:

BRM-ICT-FRM-SAPPRD26040001

Notes

• Package ini mengirim token ke Approval System menggunakan header x-access-token.
• Permission yang dibaca adalah req.userInfo.access_permission.
• Untuk endpoint read-only, gunakan READ. User WRITE tetap akan lolos.
• Untuk endpoint mutasi, gunakan WRITE.