@sodikinnaa/smart-report-plugin 2100.11.4 → 2100.11.7

package/.github/workflows/publish-npm.yml

@@ -0,0 +1,44 @@
+name: Publish to npm
+
+on:
+  push:
+    branches: [master]
+    paths:
+      - "package.json"
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 2
+
+      - name: Check if version changed
+        id: version
+        run: |
+          NEW=$(node -p "require('./package.json').version")
+          OLD=$(git show HEAD~1:package.json | node -p "JSON.parse(require('fs').readFileSync('/dev/stdin','utf8')).version")
+          if [ "$NEW" != "$OLD" ]; then
+            echo "changed=true" >> "$GITHUB_OUTPUT"
+            echo "Version changed: $OLD -> $NEW"
+          else
+            echo "changed=false" >> "$GITHUB_OUTPUT"
+            echo "Version unchanged: $NEW"
+          fi
+
+      - uses: actions/setup-node@v4
+        if: steps.version.outputs.changed == 'true'
+        with:
+          node-version: "20"
+          registry-url: "https://registry.npmjs.org"
+
+      - run: npm install
+        if: steps.version.outputs.changed == 'true'
+
+      - run: npm publish --access public
+        if: steps.version.outputs.changed == 'true'
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

package/README.md

@@ -1,43 +1,440 @@
-# Smart Report MCP Plugin for OpenClaw (v1.0.8)
+# Smart Report Plugin for OpenClaw
 
-Plugin integrasi resmi untuk menghubungkan OpenClaw dengan ekosistem **Smart Report**. Memungkinkan analisis data karyawan, laporan harian, dan dashboard KPI secara real-time.
+Plugin OpenClaw untuk integrasi ke ekosistem **Smart Report** melalui:
+- **CLI commands** untuk autentikasi dan health check
+- **chat/native commands** untuk akses cepat dari runtime OpenClaw
+- **resources** untuk expose data Smart Report ke agent/runtime
+- **tools** untuk reasoning agent berbasis data Smart Report
+- **plugin skill** agar output ke user tetap rapi dan tidak menampilkan JSON mentah
+
+README ini sudah disesuaikan dengan **alur code terbaru** di source saat ini, **termasuk perilaku `install.sh` terbaru**.
+
+## Ringkasan alur terbaru
+
+Plugin melakukan registrasi pada saat `register(api)` / `activate(api)` dipanggil, lalu:
+
+1. mendaftarkan **CLI commands**
+2. mendaftarkan **chat commands** bila runtime mendukung `registerCommand`
+3. mendaftarkan **resources**
+4. mendaftarkan **tools**
+
+Struktur registrasi utama ada di `src/index.ts`:
+- `registerCommands(api)`
+- `registerResources(api)`
+- `registerTools(api)`
+
+## Struktur plugin
+
+```text
+smart-report-plugin/
+├── package.json
+├── openclaw.plugin.json
+├── openclaw.cjs
+├── index.js
+├── install.sh
+├── src/
+│   ├── client.ts
+│   ├── commands.ts
+│   ├── resources.ts
+│   ├── tools.ts
+│   └── index.ts
+├── dist/
+│   ├── client.js
+│   ├── commands.js
+│   ├── resources.js
+│   ├── tools.js
+│   ├── index.js
+│   └── openclaw.cjs
+├── skills/
+│   └── smart-report/
+│       └── SKILL.md
+├── docs/
+│   └── USER_GUIDE.md
+└── scripts/
+    └── test-loader.js
+```
+
+## Requirement
+
+- OpenClaw terpasang dan bisa menjalankan `openclaw`
+- Node.js dan npm tersedia
+- Token API Smart Report valid
+- Runtime/plugin manager OpenClaw mengizinkan install plugin dari source repository
+
+## Instalasi
+
+### Opsi 1 — dari source repo lokal
+
+Jika repo ini sudah ada di mesin:
+
+```bash
+bash install.sh
+```
+
+### Opsi 2 — install via OpenClaw plugin manager dari path repo
+
+```bash
+openclaw plugins install /path/ke/smart-report-plugin
+```
+
+### Opsi 3 — installer via raw GitHub
+
+```bash
+bash <(curl -fsSL https://raw.githubusercontent.com/sodikinnaa/smart-report-plugin/master/install.sh)
+```
+
+## Alur installer terbaru
+
+`install.sh` sekarang mengikuti alur berikut:
+
+1. clone repository source
+2. menjalankan `npm ci` atau fallback `npm install`
+3. build plugin dengan `npm run build`
+4. validasi file penting plugin
+5. install plugin lewat **official OpenClaw plugin manager**:
+
+```bash
+openclaw plugins install <path-repo>
+```
+
+6. **tidak fallback** ke copy manual ke `~/.openclaw/extensions`
+7. bila gagal karena plugin lama sudah ada, installer akan:
+   - backup plugin lama
+   - retry install resmi **satu kali**
+8. gateway **tidak di-restart otomatis secara default**
+
+Tujuan alur ini adalah menjaga provenance/trust plugin tetap bersih dan menghindari state plugin local yang tidak ter-track.
+
+## Opsi installer
+
+Contoh penggunaan:
+
+```bash
+bash install.sh
+bash install.sh --branch main
+bash install.sh --repo https://github.com/sodikinnaa/smart-report-plugin.git
+bash install.sh --token <GITHUB_TOKEN>
+bash install.sh --skip-build
+bash install.sh --restart
+```
+
+Opsi yang tersedia:
+- `--repo <url>` → URL git source plugin
+- `--branch <name>` → branch/tag yang akan di-clone
+- `--target <path>` → reserved untuk diagnostik; bukan jalur manual install utama
+- `--token <token>` → GitHub token untuk private repo, atau gunakan env `GITHUB_TOKEN`
+- `--skip-build` → lewati `npm install` dan `npm run build`
+- `--restart` → restart `openclaw gateway` setelah install
+- `--no-restart` → alias legacy; restart tetap di-skip secara default
+
+## Batasan penting install.sh
+
+Perilaku script saat ini:
+- **wajib** ada command `git`, `node`, `npm`, dan `openclaw`
+- installer ini **hanya mendukung install via OpenClaw plugin manager**
+- script **tidak** publish ke npm dan **tidak** install dari package npm
+- jika `openclaw` tidak ditemukan, proses akan dihentikan
+- jika install via `openclaw plugins install` gagal karena alasan selain plugin lama sudah ada, script akan **stop** dan meminta environment OpenClaw diperbaiki dulu
+
+Artinya, `install.sh` memang sengaja dibuat konservatif supaya tidak menghasilkan plugin local yang untracked atau bermasalah secara provenance.
+
+## Build & test
 
-## 🚀 Quick Start
 ```bash
-# 1. Instal Plugin
-openclaw plugins install @sodikinnaa/smart-report-plugin
+npm test
+npm run build
+```
+
+Script yang tersedia di `package.json`:
+- `npm run build`
+- `npm test`
+- `npm run publish`
+
+## Konfigurasi plugin
+
+Manifest `openclaw.plugin.json` mendeklarasikan config berikut:
+
+- `apiToken`
+- `companyName`
+- `companyDomain`
+
+Contoh shape config:
+
+```json
+{
+  "apiToken": "TOKEN_SMART_REPORT",
+  "companyName": "Nama Perusahaan",
+  "companyDomain": "member.smartreport.my.id"
+}
+```
+
+## Cara autentikasi
+
+Setelah plugin ter-install, jalankan:
+
+```bash
+openclaw smart-auth <TOKEN_ANDA>
+```
+
+Perilaku `smart-auth` di code terbaru:
+- token disimpan ke `api.pluginConfig` saat runtime berjalan
+- plugin mencoba verifikasi token dengan memanggil `company/info`
+- jika sukses, plugin menyimpan:
+  - `apiToken`
+  - `companyName`
+  - `companyDomain`
+- jika `api.saveConfig()` tersedia, plugin memakai mekanisme save resmi runtime
+- jika tidak tersedia, plugin fallback ke update file config OpenClaw yang ditemukan
+
+Candidate config path yang dicoba oleh plugin:
+- `~/.openclaw/openclaw.json`
+- `~/.openclaw/config.json`
+- `/root/.openclaw/openclaw.json`
+- `/root/.openclaw/config.json`
+- `/etc/openclaw/openclaw.json`
+- `/etc/openclaw/config.json`
+
+## Cara cek konektivitas
+
+Untuk health check end-to-end, jalankan:
+
+```bash
+openclaw smart-status
+```
+
+Status check saat ini menguji method berikut:
+- `company/info`
+- `smartreport/dashboard`
+- `employees/list`
+- `reports/list`
+- `divisions/list`
+- `guides/list`
+- `analyze_performance`
+
+Jika ada check gagal, command akan exit dengan status non-zero.
+
+## CLI commands yang tersedia
 
-# 2. Aktivasi Token
-openclaw smart-auth YOUR_SECRET_TOKEN
+Plugin saat ini mendaftarkan 2 CLI command:
 
-# 3. Cek status semua fungsi MCP
+- `openclaw smart-auth <token>`
+- `openclaw smart-status`
+
+## Chat/native commands yang tersedia
+
+Jika runtime OpenClaw mendukung `registerCommand`, plugin akan mendaftarkan command berikut:
+
+- `/smart_status`
+- `/smart_dashboard`
+- `/smart_dashboard_raw`
+- `/smart_employees`
+- `/smart_employees_raw`
+- `/smart_reports`
+- `/smart_reports_raw`
+- `/smart_divisions`
+- `/smart_divisions_raw`
+- `/smart_guides`
+- `/smart_guides_raw`
+- `/smart_guide`
+- `/smart_guide_raw`
+- `/smart_analysis`
+- `/smart_analysis_raw`
+
+### Catatan penting nama command
+
+Di code terbaru, nama chat command memakai **underscore**, bukan dash.
+
+Benar:
+- `/smart_status`
+- `/smart_dashboard`
+
+Bukan:
+- `/smart-status`
+- `/smart-dashboard`
+
+## Format argumen command
+
+Command chat membaca `ctx.args` lalu mencoba parsing dengan alur berikut:
+
+1. jika kosong → `{}`
+2. jika valid JSON object → dipakai langsung
+3. jika valid JSON tapi bukan object → dibungkus sebagai `{ "input": ... }`
+4. jika bukan JSON → dibungkus sebagai `{ "input": "teks-raw" }`
+
+Contoh:
+
+```text
+/smart_reports {"per_page":5}
+/smart_guide {"id":12}
+/smart_dashboard {"mode":"compact"}
+```
+
+## Tools yang didaftarkan
+
+Plugin saat ini mendaftarkan tool berikut:
+
+- `get_daily_dashboard`
+- `get_guides_list`
+- `get_guide_content`
+- `get_list_reports`
+- `get_reports_summary`
+- `get_report_detail`
+- `get_debt_analysis`
+
+Semua tool memanggil backend MCP lalu mengembalikan hasil JSON dalam field `text`.
+
+Catatan:
+- tool memang ditujukan untuk **reasoning internal agent**
+- output ke user sebaiknya dirapikan terlebih dahulu
+- skill `smart-report` sebaiknya dipakai agar agent tidak menampilkan JSON mentah ke user
+
+## Resources yang didaftarkan
+
+Plugin mendaftarkan resource berikut:
+
+- `smartreport://reports`
+- `smartreport://employees`
+- `smartreport://divisions`
+- `smartreport://guides`
+- `smartreport://dashboard`
+
+Semua resource saat ini mengembalikan `application/json`.
+
+## Method MCP yang dipakai plugin
+
+Source `src/client.ts` saat ini memanggil endpoint:
+
+```text
+https://member.smartreport.my.id/api/mcp
+```
+
+Method MCP yang dipakai di berbagai command/resource/tool:
+- `company/info`
+- `smartreport/dashboard`
+- `employees/list`
+- `reports/list`
+- `divisions/list`
+- `guides/list`
+- `guides/get`
+- `analyze_performance`
+
+## Token resolution flow
+
+Saat melakukan request, plugin mencari token dengan urutan:
+
+1. `api.pluginConfig.apiToken`
+2. `api.config.apiToken`
+3. `api.config.plugins.entries.smart-report-plugin.config.apiToken`
+
+Jika token tidak ditemukan, plugin akan melempar error:
+
+```text
+API token not found. Jalankan "openclaw smart-auth <token>" terlebih dahulu.
+```
+
+## Kompatibilitas runtime OpenClaw terbaru
+
+Pada runtime OpenClaw yang lebih baru, command chat/native harus memakai field:
+- `handler`
+- bukan `execute`
+
+Plugin ini sudah mengikuti pola tersebut dan juga menyetel:
+- `acceptsArgs: true`
+
+Selain itu, proses registrasi chat command dibungkus `try/catch` agar kegagalan registrasi tidak ikut menjatuhkan startup plugin secara keseluruhan.
+
+## Verifikasi setelah install
+
+Langkah verifikasi yang direkomendasikan:
+
+```bash
+openclaw plugins list --verbose
+openclaw smart-auth <TOKEN_SMART_REPORT>
 openclaw smart-status
 ```
 
-## ✅ Command Tambahan
-- `openclaw smart-auth <token>` → menyimpan dan validasi token Smart Report.
-- `openclaw smart-status` → health-check semua fungsi MCP utama:
-  - `company/info`
-  - `smartreport/dashboard`
-  - `employees/list`
-  - `reports/list`
-  - `divisions/list`
-  - `guides/list`
-  - `analyze_performance`
+Output akhir `install.sh` juga memang mengarahkan verifikasi ke alur ini, lalu menyarankan pengujian chat command bila runtime mendukung native command.
+
+Jika runtime mendukung chat/native command, lanjut uji:
+
+```text
+/smart_status
+/smart_dashboard {"mode":"compact"}
+/smart_reports {"per_page":5}
+```
+
+## Dokumentasi tambahan
+
+- `docs/USER_GUIDE.md`
+- `docs/AGENT_SESSION_MCP_TROUBLESHOOTING.md`
+
+## Troubleshooting
+
+### 1. Plugin gagal install
+
+Cek:
+
+```bash
+openclaw plugins list --verbose
+openclaw plugins doctor
+```
+
+Kemungkinan penyebab:
+- trust/provenance plugin belum valid
+- plugin lama masih tercatat
+- policy OpenClaw menolak install source tertentu
+
+### 2. Auth gagal
+
+Pastikan:
+- token valid
+- endpoint Smart Report bisa diakses
+- backend menerima Bearer token
+
+Ulangi:
+
+```bash
+openclaw smart-auth <TOKEN_ANDA>
+```
+
+### 3. Command chat tidak muncul
+
+Kemungkinan:
+- runtime tidak menyediakan `registerCommand`
+- channel/runtime tidak mendukung native command plugin
+- ada error registrasi command saat startup
+
+### 4. Tool mengembalikan error
+
+Cek apakah token sudah tersimpan dan method MCP yang dipanggil memang tersedia di backend.
+
+## Manifest & metadata saat ini
+
+`package.json`
+- package name: `@sodikinnaa/smart-report-plugin`
+- version: `2100.11.6`
+
+`openclaw.plugin.json`
+- plugin id: `smart-report-plugin`
+- name: `Smart Report Integration`
+- version: `2100.11.6`
+- entrypoint: `./index.js`
 
+## Catatan desain
 
-## 📖 Dokumentasi Lengkap
-Kami telah menyediakan panduan langkah-demi-langkah untuk pengguna teknis maupun non-teknis:
-*   [**Panduan Pengguna (User Guide)**](docs/USER_GUIDE.md) - Prasyarat, Instalasi, Tooling, dan Troubleshooting.
+- registrasi dipisah per concern: `commands`, `resources`, `tools`, `client`
+- `client.ts` menangani auth, persistence config, dan call MCP
+- `commands.ts` menangani CLI + chat command
+- `resources.ts` expose dataset Smart Report sebagai resource JSON
+- `tools.ts` expose method penting untuk reasoning agent
+- skill plugin disediakan di folder `./skills`
 
-## 🛠️ Fitur Utama
-*   **MCP Integration:** Mendukung standar Model Context Protocol.
-*   **KPI Dashboard:** Data agregasi harian (Compact/Full/Ops mode).
-*   **Deep Analysis:** Tool untuk mendeteksi "Debt Performance" karyawan.
-*   **Division Aware:** Data karyawan sekarang sudah menyertakan nama divisi.
+## Rekomendasi penggunaan
 
-## ⚖️ Lisensi
-Distributed under the MIT License. See `LICENSE` for more information.
+Gunakan:
+- **CLI command** untuk setup awal dan health check
+- **chat command** untuk akses cepat/manual dari runtime
+- **tools** untuk analisis oleh agent
+- **skill** untuk merapikan output akhir ke user
 
----
-*Powered by Sultan Engine*
+Kalau ingin menjaga UX tetap bagus, jangan tampilkan raw JSON ke end-user kecuali memang untuk debugging.

package/dist/client.d.ts

@@ -0,0 +1,17 @@
+export declare const PLUGIN_ID = "smart-report-plugin";
+export declare const API_BASE = "https://member.smartreport.my.id/api/mcp";
+export type SmartReportApi = {
+    pluginConfig?: Record<string, unknown>;
+    config?: any;
+    saveConfig?: (config: Record<string, unknown>) => Promise<void> | void;
+};
+export declare function resolveToken(api: SmartReportApi): string | undefined;
+export declare function savePluginConfig(api: SmartReportApi, config: {
+    apiToken: string;
+    companyName?: string;
+    companyDomain?: string;
+}): Promise<void>;
+export declare function callMcp(api: SmartReportApi, method: string, params?: Record<string, unknown>): Promise<any>;
+export declare function normalizeToolError(error: unknown): {
+    error: string;
+};

package/dist/client.js

@@ -0,0 +1,104 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.API_BASE = exports.PLUGIN_ID = void 0;
+exports.resolveToken = resolveToken;
+exports.savePluginConfig = savePluginConfig;
+exports.callMcp = callMcp;
+exports.normalizeToolError = normalizeToolError;
+const axios_1 = __importDefault(require("axios"));
+const fs_1 = __importDefault(require("fs"));
+const os_1 = __importDefault(require("os"));
+const path_1 = __importDefault(require("path"));
+exports.PLUGIN_ID = 'smart-report-plugin';
+exports.API_BASE = 'https://member.smartreport.my.id/api/mcp';
+function resolveToken(api) {
+    const pluginToken = api?.pluginConfig?.apiToken;
+    if (typeof pluginToken === 'string' && pluginToken.trim())
+        return pluginToken;
+    const configToken = api?.config?.apiToken;
+    if (typeof configToken === 'string' && configToken.trim())
+        return configToken;
+    const nestedToken = api?.config?.plugins?.entries?.[exports.PLUGIN_ID]?.config?.apiToken;
+    if (typeof nestedToken === 'string' && nestedToken.trim())
+        return nestedToken;
+    return undefined;
+}
+function getCandidateConfigPaths() {
+    const home = os_1.default.homedir();
+    return [
+        path_1.default.join(home, '.openclaw', 'openclaw.json'),
+        path_1.default.join(home, '.openclaw', 'config.json'),
+        '/root/.openclaw/openclaw.json',
+        '/root/.openclaw/config.json',
+        '/etc/openclaw/openclaw.json',
+        '/etc/openclaw/config.json',
+    ];
+}
+function persistPluginConfigToFile(config) {
+    const configPath = getCandidateConfigPaths().find((candidate) => fs_1.default.existsSync(candidate));
+    if (!configPath) {
+        return;
+    }
+    const raw = fs_1.default.readFileSync(configPath, 'utf8');
+    const parsed = JSON.parse(raw || '{}');
+    parsed.plugins = parsed.plugins || {};
+    parsed.plugins.entries = parsed.plugins.entries || {};
+    const previousEntry = parsed.plugins.entries[exports.PLUGIN_ID] && typeof parsed.plugins.entries[exports.PLUGIN_ID] === 'object'
+        ? parsed.plugins.entries[exports.PLUGIN_ID]
+        : {};
+    const previousConfig = previousEntry.config && typeof previousEntry.config === 'object'
+        ? previousEntry.config
+        : {};
+    parsed.plugins.entries[exports.PLUGIN_ID] = {
+        ...previousEntry,
+        enabled: true,
+        config: {
+            ...previousConfig,
+            ...config,
+        },
+    };
+    fs_1.default.writeFileSync(configPath, JSON.stringify(parsed, null, 2));
+}
+async function savePluginConfig(api, config) {
+    if (typeof api.saveConfig === 'function') {
+        await api.saveConfig(config);
+        return;
+    }
+    api.pluginConfig = {
+        ...(api.pluginConfig || {}),
+        ...config,
+    };
+    persistPluginConfigToFile(config);
+}
+async function callMcp(api, method, params = {}) {
+    const token = resolveToken(api);
+    if (!token) {
+        throw new Error('API token not found. Jalankan "openclaw smart-auth <token>" terlebih dahulu.');
+    }
+    const response = await axios_1.default.post(exports.API_BASE, {
+        jsonrpc: '2.0',
+        method,
+        params,
+        id: Date.now(),
+    }, {
+        headers: {
+            Authorization: `Bearer ${token}`,
+            'Content-Type': 'application/json',
+            Accept: 'application/json',
+        },
+        timeout: 8000,
+    });
+    if (response.data?.error?.message) {
+        throw new Error(String(response.data.error.message));
+    }
+    return response.data?.result;
+}
+function normalizeToolError(error) {
+    if (error instanceof Error) {
+        return { error: error.message };
+    }
+    return { error: 'Unknown Smart Report plugin error' };
+}

package/dist/commands.d.ts

@@ -0,0 +1,13 @@
+import { SmartReportApi } from './client';
+type CommandApi = SmartReportApi & {
+    logger?: {
+        info?: (message: string) => void;
+        warn?: (message: string) => void;
+        error?: (message: string) => void;
+        debug?: (message: string) => void;
+    };
+    registerCli?: Function;
+    registerCommand?: Function;
+};
+export declare function registerCommands(api: CommandApi): void;
+export {};