hola-server 1.0.11 → 2.0.1

package/skills/msg.md

@@ -0,0 +1,30 @@
+# Message Utilities Skill
+
+## Overview
+
+The `hola-server/core/msg.js` module wraps the `wxmnode` library to provide a simplified interface for sending messages (e.g., WeChat Work or similar enterprise messengers).
+
+## Importing
+
+```javascript
+const { init_wxm, send_msg } = require("hola-server/core/msg");
+```
+
+## API Reference
+
+### `init_wxm(name, password)`
+Initializes the underlying messaging client with credentials.
+- **param**: `name` (string) - Account/Service name.
+- **param**: `password` (string) - Credentials.
+
+### `send_msg(content, type, detail)`
+Sends a message asynchronously.
+- **param**: `content` (string) - Main message body.
+- **param**: `type` (string) - Message type identifier.
+- **param**: `detail` (Object) - Additional metadata or payload options.
+- **returns**: `Promise<Object>` - Result from the messaging service.
+
+```javascript
+await init_wxm("bot_account", "secret_token");
+await send_msg("System Alert: Disk Full", "text", { priority: "high" });
+```

package/skills/number.md

@@ -0,0 +1,88 @@
+# Number Utilities Skill
+
+## Overview
+
+The `hola-server/core/number.js` module provides extensive numerical utilities including parsing, rounding, range generation, sampling, and space definitions for search algorithms.
+
+## Importing
+
+```javascript
+const {
+    parse_num, extract_number,
+    to_fixed2, round_to_fixed2,
+    range, scale,
+    space, is_space, contains_space,
+    is_integer, random_number, random_sample, lhs_samples
+} = require("hola-server/core/number");
+```
+
+## API Reference
+
+### 1. Parsing & Formatting
+
+#### `parse_num(str)`
+Parses string to float, defaults to 0 if invalid.
+- **returns**: `number`
+
+#### `to_fixed2(str)`
+Parses string/number and rounds/formats to 2 decimal places.
+- **returns**: `number`
+
+#### `round_to_fixed2(num)`
+Math utility to round a number to 2 decimal places.
+- **returns**: `number`
+
+#### `extract_number(value)`
+Extracts the first valid numeric sequence from a string.
+- **param**: `value` (string) - e.g., "Price$12.50each".
+- **returns**: `number` - e.g., 12.50.
+
+### 2. Ranges & Spaces
+
+#### `range(start, end, step)`
+Generates an arithmetic sequence.
+- `range(3)` → `[0, 1, 2]`
+- `range(1, 5)` → `[1, 2, 3, 4, 5]`
+- `range(0, 10, 2)` → `[0, 2, 4, 6, 8, 10]`
+
+#### `scale(start, end, ratio)`
+Generates a geometric sequence.
+- `scale(2, 16, 2)` → `[2, 4, 8, 16]`
+
+#### `space(min, max)`
+Creates a "space" object `{min, max}` representing a continuous range.
+- **returns**: `{min: number, max: number}`
+
+#### `is_space(value)`
+Checks if an object is a valid space (has min/max).
+- **returns**: `boolean`
+
+#### `contains_space(obj)`
+Checks if any property of an object is a space.
+- **returns**: `boolean`
+
+### 3. Random & Sampling
+
+#### `random_number(min, max)`
+Generates a random number between min and max. Returns integer if bounds are integers, otherwise float with 2 decimals.
+- **returns**: `number`
+
+#### `lhs_samples(min, max, n)`
+Generates `n` ranges using Latin Hypercube Sampling logic.
+- **returns**: `Array<{min, max}>`
+
+#### `random_sample(obj)`
+Takes a configuration object where values can be fixed, arrays (options), or spaces (range), and returns a single sampled object.
+- **Array values**: Randomly picks one element.
+- **Space values**: Randomly picks number within range.
+- **Other**: Kept as-is.
+
+```javascript
+const config = {
+    color: ['red', 'blue'],   // Pick one
+    size: space(10, 20),      // Pick number 10-20
+    type: 'shirt'             // Fixed
+};
+const sample = random_sample(config);
+// { color: 'red', size: 14.5, type: 'shirt' }
+```

package/skills/obj.md

@@ -0,0 +1,36 @@
+# Object Utilities Skill
+
+## Overview
+
+The `hola-server/core/obj.js` module provides simple object manipulation helpers.
+
+## Importing
+
+```javascript
+const { copy_obj, is_object } = require("hola-server/core/obj");
+```
+
+## API Reference
+
+### `copy_obj(obj, attrs)`
+Creates a shallow copy of an object containing only the specified attributes (whitelisting).
+- **param**: `obj` (Object) - Source object.
+- **param**: `attrs` (string[]) - Keys to copy.
+- **returns**: `Object`
+
+```javascript
+const src = { a: 1, b: 2, c: 3 };
+const dest = copy_obj(src, ['a', 'c']);
+// dest is { a: 1, c: 3 }
+```
+
+### `is_object(obj)`
+Checks if a value is a plain non-null object (excludes arrays and null).
+- **param**: `obj` (*) - Value to check.
+- **returns**: `boolean`
+
+```javascript
+is_object({}); // true
+is_object([]); // false
+is_object(null); // false
+```

package/skills/params.md

@@ -0,0 +1,206 @@
+# HTTP Parameter Utilities Skill
+
+## Overview
+
+The `hola-server/http/params.js` module provides utilities for extracting and validating parameters from Express request objects (query strings and body).
+
+## Importing
+
+```javascript
+const { 
+    get_params, post_params, post_update_params,
+    required_get_params, required_post_params, required_params
+} = require("hola-server/http/params");
+```
+
+## API Reference
+
+### 1. Extract Query Parameters
+
+#### `get_params(req, params)`
+Extracts specified parameters from `req.query` (only values that are present).
+
+**Parameters:**
+- `req` (Object): Express request object
+- `params` (string[]): Parameter names to extract
+
+**Returns:** `Object` - Extracted parameters
+
+```javascript
+// URL: /api/products?name=iPhone&price=999&stock=50
+
+const params = get_params(req, ["name", "price", "category"]);
+// Returns: { name: "iPhone", price: "999" }
+// Note: "category" is omitted (not present in query)
+```
+
+### 2. Extract Body Parameters
+
+#### `post_params(req, params)`
+Extracts specified parameters from `req.body` (only non-empty values).
+
+```javascript
+const params = post_params(req, ["name", "email", "age"]);
+// Returns only fields that have values
+```
+
+#### `post_update_params(req, params)`
+Extracts update parameters, **including `null` and empty strings** (but excluding `undefined`).
+
+**Use Case:** Partial updates where empty string means "clear field" and undefined means "no change".
+
+```javascript
+// Body: { name: "John", email: "", age: undefined }
+
+const params = post_update_params(req, ["name", "email", "age"]);
+// Returns: { name: "John", email: "" }
+// Note: "age" is omitted (undefined), "email" is included (empty string is valid)
+```
+
+### 3. Required Parameters
+
+#### `required_get_params(req, params)`
+Extracts required query parameters. Returns `null` if any are missing.
+
+```javascript
+const { NO_PARAMS } = require("hola-server/http/code");
+
+const params = required_get_params(req, ["page", "limit"]);
+if (!params) {
+    return res.json({ code: NO_PARAMS, err: ["page", "limit"] });
+}
+// params contains both page and limit, or null
+```
+
+#### `required_post_params(req, params)`
+Extracts required body parameters. Returns `null` if any are missing.
+
+```javascript
+const { NO_PARAMS } = require("hola-server/http/code");
+
+const params = required_post_params(req, ["username", "password"]);
+if (!params) {
+    return res.json({ code: NO_PARAMS, err: ["username", "password"] });
+}
+```
+
+#### `required_params(input, params)`
+General-purpose required parameter extraction from any object.
+
+```javascript
+const params = required_params(req.body, ["name", "email"]);
+if (!params) {
+    return res.json({ code: NO_PARAMS, err: ["name", "email"] });
+}
+```
+
+## Usage Patterns
+
+### Pattern 1: Optional Query Parameters
+
+```javascript
+router.get("/search", async (req, res) => {
+    const search = get_params(req, ["name", "category", "min_price", "max_price"]);
+    
+    const results = await entity.list_entity(
+        { attr_names: "name,price,category", page: 1, limit: 20, sort_by: "price", desc: "false" },
+        {},
+        search,  // Only includes parameters that were provided
+        "*"
+    );
+    
+    return res.json(results);
+});
+```
+
+### Pattern 2: Required Body Parameters
+
+```javascript
+const { NO_PARAMS, SUCCESS } = require("hola-server/http/code");
+
+router.post("/login", async (req, res) => {
+    const credentials = required_post_params(req, ["username", "password"]);
+    
+    if (!credentials) {
+        return res.json({ code: NO_PARAMS, err: ["username", "password"] });
+    }
+    
+    // Proceed with authentication
+    const user = await authenticate(credentials.username, credentials.password);
+    return res.json({ code: SUCCESS, user });
+});
+```
+
+### Pattern 3: Partial Updates
+
+```javascript
+router.put("/:id", async (req, res) => {
+    // Use post_update_params to allow clearing fields with empty strings
+    const updates = post_update_params(req, ["name", "description", "email", "phone"]);
+    
+    const result = await entity.update_entity(req.params.id, updates, "*");
+    return res.json(result);
+});
+```
+
+### Pattern 4: Pagination Parameters
+
+```javascript
+router.get("/list", async (req, res) => {
+    const query_params = get_params(req, ["page", "limit", "sort_by", "desc"]);
+    
+    // Provide defaults
+    query_params.page = query_params.page || 1;
+    query_params.limit = query_params.limit || 20;
+    query_params.sort_by = query_params.sort_by || "created_at";
+    query_params.desc = query_params.desc || "true";
+    query_params.attr_names = "name,price,created_at";
+    
+    const result = await entity.list_entity(query_params, {}, {}, "*");
+    return res.json(result);
+});
+```
+
+### Pattern 5: Combining Query and Body
+
+```javascript
+const { NO_PARAMS } = require("hola-server/http/code");
+
+router.post("/filter", async (req, res) => {
+    // Extract pagination from query
+    const pagination = required_get_params(req, ["page", "limit"]);
+    if (!pagination) {
+        return res.json({ code: NO_PARAMS, err: ["page", "limit"] });
+    }
+    
+    // Extract filter from body
+    const filters = post_params(req, ["category", "min_price", "max_price", "brand"]);
+    
+    const results = await entity.list_entity(
+        { ...pagination, attr_names: "name,price", sort_by: "price", desc: "false" },
+        {},
+        filters,
+        "*"
+    );
+    
+    return res.json(results);
+});
+```
+
+## Best Practices
+
+1. **Use `required_*` functions for validation**: They return `null` if parameters are missing, making validation simple.
+
+2. **Use `post_update_params` for PATCH/PUT**: Distinguishes between "clear field" (empty string) and "no change" (undefined).
+
+3. **Provide defaults for optional params**: After extracting with `get_params` or `post_params`, apply defaults as needed.
+
+4. **Whitelist parameters**: Always specify exact parameter names to avoid exposing internal fields.
+
+```javascript
+// Good: explicit whitelist
+const params = post_params(req, ["name", "email", "age"]);
+
+// Avoid: accepting all body params
+const params = req.body;  // Could include malicious/internal fields
+```

package/skills/random.md

@@ -0,0 +1,22 @@
+# Random Utilities Skill
+
+## Overview
+
+The `hola-server/core/random.js` module provides simple random generation utilities.
+
+## Importing
+
+```javascript
+const { random_code } = require("hola-server/core/random");
+```
+
+## API Reference
+
+### `random_code()`
+Generates a random 6-digit integer code (0 to 999999).
+- **returns**: `number`
+
+```javascript
+const code = random_code();
+// e.g., 123456
+```

package/skills/role.md

@@ -0,0 +1,59 @@
+# Role & Permission Utilities Skill
+
+## Overview
+
+The `hola-server/core/role.js` module provides utilities for checking user roles and permissions against entity meta definitions and system settings.
+
+## Importing
+
+```javascript
+const { 
+    is_root_role, is_root_user, 
+    validate_meta_role, check_user_role, 
+    get_user_role_right, get_session_user 
+} = require("hola-server/core/role");
+```
+
+## API Reference
+
+### 1. Role Validation
+
+#### `validate_meta_role(role_name)`
+Checks if a role name exists in the system settings.
+- **param**: `role_name` (string)
+- **returns**: `boolean`
+
+#### `is_root_role(role_name)`
+Checks if a specific role has root privileges (based on settings).
+- **returns**: `boolean`
+
+### 2. User & Session Checks
+
+#### `get_session_user(req)`
+Extracts user object from request session.
+- **param**: `req` (Object) - Express request object.
+- **returns**: `Object|null`
+
+#### `is_root_user(req)`
+Checks if the current session user has root privileges.
+- **returns**: `boolean`
+
+### 3. Permission Checking
+
+#### `get_user_role_right(req, meta)`
+Resolves the current user's permissions for a specific entity based on their role.
+- **param**: `req` (Object) - HTTP request.
+- **param**: `meta` (Object) - Entity meta definition.
+- **returns**: `[mode, view]` - Tuple of allowed modes (e.g., "crud") and view ID.
+
+#### `check_user_role(req, meta, mode, view)`
+Verifies if the current user has specific access rights.
+- **param**: `mode` (string) - Required operation mode (c/r/u/d).
+- **param**: `view` (string) - Required view access.
+- **returns**: `boolean` - True if permitted.
+
+```javascript
+if (check_user_role(req, productMeta, 'c', '*')) {
+    // User can create products
+}
+```