@restforgejs/platform 5.2.16 → 5.3.5

package/generators/lib/sdk/naming.js

@@ -0,0 +1,48 @@
+'use strict';
+
+/**
+ * Helper penamaan untuk generator SDK.
+ *
+ * Sumber slug = key endpoint di `metadata/<project>.json` (segment route nyata,
+ * lihat src/modules/<project>.js yang me-mount router dengan
+ * `/api/<project>/<basename-file>`). Dari slug itu diturunkan:
+ * - client key  : camelCase  (`guest-book` -> `guestBook`)   — key di object createClient()
+ * - factory     : PascalCase (`guest-book` -> `GuestBook`)    — nama function createXxxResource
+ * - file/global : kebab/Pascal sesuai konteks
+ *
+ * Semua turunan deterministik: split pada batas `-`, `_`, spasi, dan batas camelCase.
+ */
+
+function splitWords(input) {
+    return String(input == null ? '' : input)
+        .replace(/([a-z0-9])([A-Z])/g, '$1 $2')
+        .split(/[-_\s]+/)
+        .map((word) => word.trim())
+        .filter(Boolean);
+}
+
+function capitalize(word) {
+    if (!word) return '';
+    return word.charAt(0).toUpperCase() + word.slice(1);
+}
+
+function toKebab(input) {
+    return splitWords(input).map((word) => word.toLowerCase()).join('-');
+}
+
+function toCamel(input) {
+    const words = splitWords(input).map((word) => word.toLowerCase());
+    if (words.length === 0) return '';
+    return words[0] + words.slice(1).map(capitalize).join('');
+}
+
+function toPascal(input) {
+    return splitWords(input).map((word) => capitalize(word.toLowerCase())).join('');
+}
+
+module.exports = {
+    splitWords,
+    toKebab,
+    toCamel,
+    toPascal
+};

package/generators/lib/sdk/runtime/README.md.tmpl

@@ -0,0 +1,207 @@
+# __PROJECT__ SDK
+
+Auto-generated JavaScript SDK for the `__PROJECT__` RESTForge backend — a thin layer over the
+REST API so you call `client.<resource>.<verb>(payload)` instead of hand-writing
+`fetch` / `$.ajax`. Generated by `restforge project sdk`.
+
+> Do not edit `src/` by hand. Regenerate with
+> `restforge project sdk --generate --project=__PROJECT__ --force`.
+
+## Overview
+
+- Base URL: `__BASEURL__`
+- Global (IIFE / browser): `window.__GLOBAL__`
+- Auth: __AUTH_OVERVIEW__
+
+## Resources
+
+| Resource | Client accessor | Primary key | Methods |
+|----------|-----------------|-------------|---------|
+__RESOURCE_TABLE__
+
+Method names follow the SDK mapping: `workflow` becomes `changeStatus`, enabling `lookup`
+also adds `lookupDynamic` (GET search), and `export` / `import` are not generated.
+
+## Fields per Resource
+
+Field lists are derived from each resource's payload (`fieldValidation`). Auto-generated
+primary keys and audit columns are filled by the backend — you do not send them on `create`.
+Other fields (including optional auto-filled ones) may be sent.
+
+__RESOURCE_FIELDS__
+
+## Layout
+
+```
+__PROJECT__/
+├── package.json
+├── tsup.config.js
+├── deploy.mjs        # copy build into a frontend app js/ folder
+├── sdk-client.js     # browser bootstrap (baseUrl baked in)
+├── README.md
+└── src/
+    ├── core/
+__CORE_TREE__
+    ├── resources/
+__RESOURCE_TREE__
+    └── index.js
+```
+
+## Install & Build
+
+```bash
+npm install
+npm run build
+```
+
+`npm run build` produces three formats in `dist/`:
+
+- `dist/index.js` — ESM (bundlers, `<script type="module">`)
+- `dist/index.cjs` — CommonJS (Node.js / SSR)
+- `dist/index.global.js` — IIFE global (`window.__GLOBAL__`) for classic `<script>`
+
+## Deploy to a Frontend App (Vanilla)
+
+```bash
+npm run deploy
+# or: node deploy.mjs <path-to-app>/js
+```
+
+Copies the build into `<app>/js/sdk/` and `sdk-client.js` into `<app>/js/sdk-client.js`.
+Then add to the HTML page, before other classic scripts:
+
+```html
+<script type="module" src="js/sdk-client.js"></script>
+```
+
+## Usage
+
+### Vanilla JS (no bundler)
+
+`sdk-client.js` sets up the global client (baseUrl already baked in):
+
+```js
+// js/sdk-client.js (generated)
+import { createClient } from './sdk/index.js';
+window.__GLOBAL__ = createClient({ baseUrl: '__BASEURL__' });
+```
+
+Then in each page script (classic `<script>`), wrap the resource you need in a `getResource()`
+helper — the same convention used by generated pages — and call its methods with
+`.then()` / `.catch()`:
+
+```js
+// name getResource() after the resource this page uses
+function getResource() {
+    return window.__GLOBAL__.__FIRST_KEY__;
+}
+
+// list (server-side, DataTables-compatible): pass the raw response to DataTables
+getResource().datatables({ start: 0, length: 10, search: { value: '' }, sort_columns: [] })
+    .then(function (json) { /* json.data, json.recordsTotal, json.draw */ })
+    .catch(function (err) { console.error(err.message); });
+
+// create (update is the same but the body must include the primary key)
+getResource().create(__FIRST_CREATE_BODY__)
+    .then(function (response) { /* response.success, response.data */ })
+    .catch(function (err) { console.error(err.message); });
+
+// fetch one by primary key — the record is response.data[0]
+getResource().first({ where: [{ key: '__FIRST_PK__', value: '...' }] })
+    .then(function (response) {
+        if (response.success && response.data && response.data.length > 0) {
+            var item = response.data[0];
+        }
+    });
+
+// delete by primary key
+getResource().delete({ where: [{ key: '__FIRST_PK__', value: '...' }] })
+    .then(function (response) { /* reload list */ });
+```
+
+### Bundler (Vite, webpack, Next.js)
+
+```bash
+npm install file:<path-to-this-folder>
+```
+
+```js
+import { createClient } from '__PROJECT__';
+
+const client = createClient({ baseUrl: '__BASEURL__' });
+const list = await client.__FIRST_KEY__.datatables({ start: 0, length: 10 });
+```
+
+### Error Handling
+
+```js
+import { ApiError } from '__PROJECT__';
+
+try {
+    await client.__FIRST_KEY__.create(__FIRST_CREATE_BODY__);
+} catch (err) {
+    if (err instanceof ApiError) {
+        console.log(err.status, err.body); // HTTP status + backend response body
+    }
+}
+```
+
+__AUTH_SECTION__## Request & Response Conventions
+
+All methods are POST with a JSON body, except `lookupDynamic` which is GET. The SDK sets
+`Content-Type: application/json` and the `x-request-mode` header automatically; you only pass
+the body shown below.
+
+### Response envelope
+
+Most endpoints return:
+
+```json
+{ "success": true, "data": ... , "message": "..." }
+```
+
+- `create` / `update`: `data` is the affected record (object).
+- `first` / `read` / `lookup`: `data` is an **array** of records — a single record is `data[0]`.
+- `datatables`: returns DataTables shape directly (`data`, `recordsTotal`, `recordsFiltered`, `draw`); `read` (paginated) adds `pagination`.
+
+On failure the SDK throws `ApiError` with `.message`, `.status` (HTTP code), and `.body`
+(the parsed error response).
+
+### Body shape per method
+
+| Method | Body |
+|--------|------|
+| `create` | object of writable fields (see Fields per Resource) |
+| `update` | writable fields **plus the primary key** |
+| `delete` | `{ where: [{ key, value }] }` |
+| `first` | `{ where: [{ key, value }], select?: string[] }` (also accepts a single `{ key, value }` object); returns one record |
+| `read` | `{ page, per_page }` (paginated) or `{ limit }` (non-paginated); optional `search_value`, `search_by`, `sort_columns`, `where`, `select` |
+| `datatables` | `{ start, length, search, searchBy, filters, sort_columns, where }` |
+| `lookup` | `{ where?, select?, sort_columns? }` (static lookup) |
+| `lookupDynamic` | `{ search }` (sent as query string) |
+| `changeStatus` | `{ <primaryKey>, status, ... }` (workflow transition) |
+
+### `where` formats
+
+```js
+// equality, array form (delete, first, read, datatables, lookup)
+where: [{ key: '__FIRST_PK__', value: '...' }]
+
+// first also accepts a single object
+where: { key: '__FIRST_PK__', value: '...' }
+
+// advanced (read / datatables / lookup)
+where: {
+    logic: 'OR',
+    conditions: [
+        { key: '__FIRST_PK__', operator: 'like', value: '%abc%' },
+        { key: '__FIRST_PK__', value: 'exact' }
+    ]
+}
+```
+
+### Sorting
+
+```js
+sort_columns: [{ column: '__FIRST_PK__', direction: 'ASC' }]
+```

package/generators/lib/sdk/runtime/auth-client.js

@@ -0,0 +1,186 @@
+// Login/logout/refresh token + sesi user untuk auth extension RESTForge (`project auth`).
+//
+// Endpoint mengikuti router rfx_auth yang dipasang `project auth`, di-mount di bawah baseUrl
+// resource yang sama: {baseUrl}/rfx_auth/login | /refresh | /logout | /me | /register | /reset-password.
+// Tidak memakai app_code (itu khusus auth eksternal/multi-tenant, bukan project auth self-hosted).
+//
+// Response backend dibungkus { success, data: {...} }; token diambil dari data.access_token /
+// data.refresh_token, user dari data.user (login) atau data (me).
+
+import { ApiError } from './http-client.js';
+
+const STORAGE_KEYS = {
+    accessToken: 'auth_access_token',
+    refreshToken: 'auth_refresh_token',
+    user: 'auth_user'
+};
+
+export function createAuthClient({ baseUrl, storage }) {
+    if (!baseUrl) throw new Error('createAuthClient: baseUrl wajib diisi');
+    if (!storage) throw new Error('createAuthClient: storage wajib diisi');
+
+    let refreshPromise = null;
+
+    function getAccessToken() {
+        return storage.get(STORAGE_KEYS.accessToken);
+    }
+
+    function getRefreshToken() {
+        return storage.get(STORAGE_KEYS.refreshToken);
+    }
+
+    function getCurrentUser() {
+        const raw = storage.get(STORAGE_KEYS.user);
+        if (!raw) return null;
+        try {
+            return JSON.parse(raw);
+        } catch {
+            return null;
+        }
+    }
+
+    function isAuthenticated() {
+        const token = getAccessToken();
+        return !!token && !isTokenExpired(token);
+    }
+
+    function hasPermission(permissionName) {
+        const user = getCurrentUser();
+        if (!user || !Array.isArray(user.permissions)) return false;
+        return user.permissions.some((p) => (typeof p === 'string' ? p === permissionName : p.name === permissionName || p.code === permissionName));
+    }
+
+    function hasRole(roleName) {
+        const user = getCurrentUser();
+        if (!user || !Array.isArray(user.roles)) return false;
+        return user.roles.some((r) => (typeof r === 'string' ? r === roleName : r.name === roleName || r.code === roleName));
+    }
+
+    async function login(username, password) {
+        const data = await requestJson('POST', '/login', { username, password });
+        storeSession(data);
+        return getCurrentUser();
+    }
+
+    async function google(credential) {
+        // credential: Google ID token (JWT) dari Google Identity Services.
+        // Backend memverifikasi token, find-or-create user, lalu menerbitkan
+        // access/refresh token sama seperti login biasa.
+        const data = await requestJson('POST', '/google', { credential });
+        storeSession(data);
+        return getCurrentUser();
+    }
+
+    async function register(payload) {
+        // payload: { username, password, email?, full_name? }
+        return requestJson('POST', '/register', payload);
+    }
+
+    async function resetPassword(payload) {
+        // payload: { email, new_password, confirm_password }
+        return requestJson('POST', '/reset-password', payload);
+    }
+
+    function logout() {
+        const refreshToken = getRefreshToken();
+        const accessToken = getAccessToken();
+        clearSession();
+
+        // Fire-and-forget: invalidasi refresh token di server, tidak menunggu hasilnya.
+        fetch(baseUrl + '/logout', {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+                ...(accessToken ? { Authorization: `Bearer ${accessToken}` } : {})
+            },
+            body: JSON.stringify(refreshToken ? { refresh_token: refreshToken } : {})
+        }).catch(() => {});
+    }
+
+    async function refresh() {
+        if (refreshPromise) return refreshPromise;
+        refreshPromise = doRefresh();
+        try {
+            return await refreshPromise;
+        } finally {
+            refreshPromise = null;
+        }
+    }
+
+    async function doRefresh() {
+        const refreshToken = getRefreshToken();
+        if (!refreshToken) {
+            throw new Error('Refresh token tidak tersedia');
+        }
+        const data = await requestJson('POST', '/refresh', { refresh_token: refreshToken });
+        storeSession(data);
+        return data;
+    }
+
+    async function getMe() {
+        const accessToken = getAccessToken();
+        const response = await fetch(baseUrl + '/me', {
+            headers: accessToken ? { Authorization: `Bearer ${accessToken}` } : {}
+        });
+        const result = await response.json().catch(() => null);
+        if (!response.ok) {
+            throw new ApiError(result?.message || 'Failed to fetch profile data', response.status, result);
+        }
+        const userData = result?.data ?? result;
+        storage.set(STORAGE_KEYS.user, JSON.stringify(userData));
+        return userData;
+    }
+
+    async function requestJson(method, path, body) {
+        const response = await fetch(baseUrl + path, {
+            method,
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify(body)
+        });
+        const result = await response.json().catch(() => null);
+        if (!response.ok) {
+            throw new ApiError(result?.message || 'Request failed', response.status, result);
+        }
+        return result?.data ?? result;
+    }
+
+    function storeSession(data) {
+        if (!data) return;
+        if (data.access_token) storage.set(STORAGE_KEYS.accessToken, data.access_token);
+        if (data.refresh_token) storage.set(STORAGE_KEYS.refreshToken, data.refresh_token);
+        if (data.user) storage.set(STORAGE_KEYS.user, JSON.stringify(data.user));
+    }
+
+    function clearSession() {
+        storage.remove(STORAGE_KEYS.accessToken);
+        storage.remove(STORAGE_KEYS.refreshToken);
+        storage.remove(STORAGE_KEYS.user);
+    }
+
+    function isTokenExpired(token) {
+        try {
+            const payload = token.split('.')[1];
+            const decoded = JSON.parse(atob(payload.replace(/-/g, '+').replace(/_/g, '/')));
+            if (!decoded.exp) return false;
+            return decoded.exp < Math.floor(Date.now() / 1000) + 30;
+        } catch {
+            return true;
+        }
+    }
+
+    return {
+        login,
+        google,
+        register,
+        resetPassword,
+        logout,
+        refresh,
+        getMe,
+        getAccessToken,
+        getRefreshToken,
+        getCurrentUser,
+        isAuthenticated,
+        hasPermission,
+        hasRole
+    };
+}

package/generators/lib/sdk/runtime/deploy.mjs.tmpl

@@ -0,0 +1,85 @@
+#!/usr/bin/env node
+/**
+ * Deploy the __PROJECT__ SDK into a frontend app's js/ folder.
+ *
+ * Run from inside this sdk/ folder:
+ *   node deploy.mjs [path-to-app-js-folder]      or      npm run deploy
+ *
+ * What it does (all interaction is contained in this file):
+ *   1. Resolves the target app js/ folder (from the argument, or asks for it).
+ *   2. Builds dist/ automatically when it is missing (runs `npm run build`).
+ *   3. Copies the built files into <js>/sdk/ (index.js, index.cjs, index.global.js).
+ *   4. Copies sdk-client.js into <js>/sdk-client.js (skipped if it already exists).
+ *   5. Prints the <script> tag to add to the HTML page.
+ *
+ * No external dependencies — Node built-ins only.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import readline from 'node:readline';
+import { fileURLToPath } from 'node:url';
+import { spawnSync } from 'node:child_process';
+
+const SDK_DIR = path.dirname(fileURLToPath(import.meta.url));
+const PROJECT = '__PROJECT__';
+const DIST_DIR = path.join(SDK_DIR, 'dist');
+const CLIENT_FILE = path.join(SDK_DIR, 'sdk-client.js');
+
+function ask(question) {
+    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+    return new Promise((resolve) => rl.question(question, (answer) => { rl.close(); resolve(answer); }));
+}
+
+function fail(message) {
+    console.error(`\nDeploy failed: ${message}`);
+    process.exit(1);
+}
+
+async function main() {
+    // 1. Target app js/ folder: from argv, or ask.
+    let target = process.argv[2];
+    if (!target) {
+        target = (await ask('Target app js/ folder path: ')).trim();
+    }
+    if (!target) fail('No target js/ folder provided.');
+    target = path.resolve(target);
+    if (!fs.existsSync(target) || !fs.statSync(target).isDirectory()) {
+        fail(`Target folder not found: ${target}`);
+    }
+
+    // 2. Ensure dist/ exists; build automatically when missing.
+    if (!fs.existsSync(path.join(DIST_DIR, 'index.js'))) {
+        console.log('dist/ not found — running "npm run build"...');
+        const built = spawnSync('npm', ['run', 'build'], { cwd: SDK_DIR, stdio: 'inherit', shell: true });
+        if (built.status !== 0) fail('"npm run build" failed. Run "npm install" first if needed.');
+    }
+
+    // 3. Copy built files into <js>/sdk/.
+    const destSdk = path.join(target, 'sdk');
+    fs.mkdirSync(destSdk, { recursive: true });
+    for (const file of fs.readdirSync(DIST_DIR)) {
+        fs.copyFileSync(path.join(DIST_DIR, file), path.join(destSdk, file));
+    }
+
+    // 4. Copy sdk-client.js into <js>/sdk-client.js (do not clobber a customized one).
+    const destClient = path.join(target, 'sdk-client.js');
+    let clientWritten = false;
+    if (fs.existsSync(CLIENT_FILE)) {
+        if (fs.existsSync(destClient)) {
+            console.log('sdk-client.js already exists in target — kept as is (delete it to regenerate).');
+        } else {
+            fs.copyFileSync(CLIENT_FILE, destClient);
+            clientWritten = true;
+        }
+    }
+
+    // 5. Instructions.
+    console.log(`\nSDK '${PROJECT}' deployed into: ${target}`);
+    console.log(`  sdk/            (built client: index.js, index.cjs, index.global.js)`);
+    console.log(`  sdk-client.js   (${clientWritten ? 'written' : 'kept existing / not generated'})`);
+    console.log('\nAdd this to the HTML page, BEFORE other classic scripts:');
+    console.log('  <script type="module" src="js/sdk-client.js"></script>');
+    console.log('\nThen use window.<project> in your page scripts. Adjust baseUrl inside sdk-client.js if needed.');
+}
+
+main().catch((err) => fail(err && err.message ? err.message : String(err)));

package/generators/lib/sdk/runtime/http-client.js

@@ -0,0 +1,81 @@
+// Wrapper fetch generik: base URL, header auth, retry sekali saat 401, normalize response/error.
+// Tidak tahu apa pun soal login/storage — hanya menerima callback getAccessToken/refreshAccessToken
+// yang di-inject dari luar (lihat core/auth-client.js dan src/index.js).
+
+export class ApiError extends Error {
+    constructor(message, status, body) {
+        super(message);
+        this.name = 'ApiError';
+        this.status = status;
+        this.body = body;
+    }
+}
+
+export class HttpClient {
+    constructor({ baseUrl, getAccessToken, refreshAccessToken, onSessionExpired } = {}) {
+        if (!baseUrl) {
+            throw new Error('HttpClient: baseUrl wajib diisi');
+        }
+
+        this.baseUrl = baseUrl;
+        this.getAccessToken = getAccessToken || (() => null);
+        this.refreshAccessToken = refreshAccessToken || (() => Promise.reject(new Error('refreshAccessToken tidak tersedia')));
+        this.onSessionExpired = onSessionExpired || (() => {});
+    }
+
+    post(path, body = {}, options = {}) {
+        return this._request('POST', path, body, options);
+    }
+
+    get(path, options = {}) {
+        return this._request('GET', path, undefined, options);
+    }
+
+    async _request(method, path, body, options = {}, isRetry = false) {
+        const headers = { ...(options.headers || {}) };
+
+        const token = this.getAccessToken();
+        if (token) {
+            headers['Authorization'] = `Bearer ${token}`;
+        }
+
+        const isFormData = typeof FormData !== 'undefined' && body instanceof FormData;
+        if (method !== 'GET' && !isFormData && !headers['Content-Type']) {
+            headers['Content-Type'] = 'application/json';
+        }
+
+        const response = await fetch(this.baseUrl + path, {
+            method,
+            headers,
+            body: method === 'GET' ? undefined : (isFormData ? body : JSON.stringify(body))
+        });
+
+        if (response.status === 401 && !isRetry) {
+            try {
+                await this.refreshAccessToken();
+            } catch {
+                this.onSessionExpired();
+                throw new ApiError('Session has expired. Please log in again.', 401, null);
+            }
+            return this._request(method, path, body, options, true);
+        }
+
+        const result = await this._parseJson(response);
+
+        if (!response.ok) {
+            throw new ApiError(result?.message || `Request failed with status ${response.status}`, response.status, result);
+        }
+
+        return result;
+    }
+
+    async _parseJson(response) {
+        const text = await response.text();
+        if (!text) return null;
+        try {
+            return JSON.parse(text);
+        } catch {
+            return null;
+        }
+    }
+}

package/generators/lib/sdk/runtime/resource-client.js

@@ -0,0 +1,59 @@
+// Generic builder verb CRUD per resource.
+// Descriptor (slug, primaryKey, action) berasal 1:1 dari payload RDF backend
+// (mis. backend/payload/category.json) — generator cukup salin field tableName-slug,
+// primaryKey, dan action ke sini, tanpa transformasi tambahan.
+
+// Verb yang nama method-nya tidak sama dengan nama path REST (camelCase action key
+// tidak selalu sama dengan kebab-case path).
+const VERB_OVERRIDES = {
+    workflow: { method: 'changeStatus', path: 'change-status' }
+};
+
+// export & import sengaja TIDAK di-generate otomatis di sini: alurnya multi-step
+// (upload/preview/commit/status/download), didesain terpisah saat resource yang
+// memakainya sudah dibutuhkan di pilot ini.
+const SKIP_VERBS = ['export', 'import'];
+
+// lookup selalu dipanggil SDK lewat POST (mode "static" backend) — endpoint juga
+// punya mode GET ("dynamic", untuk search-as-you-type), tapi itu di luar scope SDK
+// generic ini. Header ini wajib supaya backend tidak salah baca mode.
+const VERB_REQUEST_OPTIONS = {
+    lookup: { headers: { 'x-request-mode': 'static' } }
+};
+
+function camelToKebab(text) {
+    return text.replace(/([a-z0-9])([A-Z])/g, '$1-$2').toLowerCase();
+}
+
+/**
+ * @param {object} http - instance dari core/http-client.js, kontrak: http.post(path, body, options) => Promise<json>
+ * @param {object} descriptor - { slug, primaryKey, action }
+ */
+export function createResource(http, descriptor) {
+    const { slug, primaryKey, action = {} } = descriptor;
+    const resource = { slug, primaryKey };
+
+    for (const [verb, isActive] of Object.entries(action)) {
+        if (!isActive || SKIP_VERBS.includes(verb)) continue;
+
+        const override = VERB_OVERRIDES[verb];
+        const method = override ? override.method : verb;
+        const path = override ? override.path : camelToKebab(verb);
+        const requestOptions = VERB_REQUEST_OPTIONS[verb];
+
+        resource[method] = (body = {}) => http.post(`/${slug}/${path}`, body, requestOptions);
+    }
+
+    // lookupDynamic: varian GET dari endpoint /lookup yang sama, untuk search-as-you-type
+    // (mis. select2 remote ajax) — backend MEMANG memfilter via query `search` hanya di mode
+    // ini, mode POST static di atas tidak punya parameter search sama sekali.
+    if (action.lookup) {
+        resource.lookupDynamic = (params = {}) => {
+            const query = new URLSearchParams(params).toString();
+            const path = `/${slug}/lookup${query ? `?${query}` : ''}`;
+            return http.get(path, { headers: { 'x-request-mode': 'dynamic' } });
+        };
+    }
+
+    return resource;
+}