seishiro 0.1.6-untest → 0.1.8-dev

package/README.md

@@ -11,7 +11,8 @@ Seishiro eliminates the complexity of routing folder structures and replaces the
 - [x] Protocol Response
 - [x] Middleware Runner
 - [x] Action Executed
-- [ ] Versioning Header
+- [ ] Versioning Header (Pending...)
+- [ ] Language Switch (Pending...)
 
 ## Installation
 
@@ -24,7 +25,7 @@ Seishiro eliminates the complexity of routing folder structures and replaces the
    yarn add seishiro
    ```
 
-2. Copy the file `./example/api/action.(js/ts)` and then copy some of its structure for the sample. You can manage this system to be much more complex.
+2. Copy the file example and then copy some of its structure for the sample. You can manage this system to be much more complex.
 3. Set up and customize it as you like.
 4. Add auth-cookie to put the default placeholder and client version.
 5. Boom! Done!

package/{lib → cjs/lib}/actions.d.ts

@@ -3,24 +3,53 @@ import RegistryBuilder from "./registry";
 import MessageBuilder from "./message";
 import PolicyBuilder from "./policy";
 /**
- * @name Actions
+ * @class Actions
+ * @description The main orchestrator of the Seishiro API. It handles the execution flow
+ * by coordinating between Registry, Message, and Policy builders across different protocols.
  */
 export default class Actions {
     private registry;
     private message;
     private policy;
+    /**
+     * @constructor
+     * @param {Object} params - Configuration instances.
+     * @param {RegistryBuilder} params.registry - Instance to manage route/controller mapping.
+     * @param {MessageBuilder} params.message - Instance to handle localized error/response messages.
+     * @param {PolicyBuilder} params.policy - Instance to manage security and versioning rules.
+     */
     constructor({ registry, message, policy, }: {
         registry: RegistryBuilder;
         message: MessageBuilder;
         policy: PolicyBuilder;
     });
+    /**
+     * @method BookRegistry
+     * @description Generates an encrypted list of available API registries and application versions.
+     * This is used to securely expose allowed actions to the client side.
+     * @returns {Object} An object containing encryption metadata (iv, type_base) and the encrypted 'data' string.
+     */
     BookRegistry(): {
         iv_length: number;
         type_base: string;
         iv: string;
         data: string;
     };
+    /**
+     * @method ResponseBuilder
+     * @private
+     * @description Standardizes the response structure for all action types, handling headers, cookies, and errors.
+     * @param {any} dataRes - The raw result or error object from the controller/middleware.
+     * @param {RegistryParams["system"]} system - The system context (headers, cookies, ip, etc.) from the request.
+     * @returns {Object} A unified response object containing headers, cookies, status code, and the final data/error payload.
+     */
     private ResponseBuilder;
+    /**
+     * @method SystemAction
+     * @description The core execution engine that processes controllers and middlewares.
+     * @param {RegistryParams} params - The request payload containing system info, type, data, and optional middleware state.
+     * @returns {Promise<Object>} A promise that resolves to a standardized response object via ResponseBuilder.
+     */
     SystemAction({ system, middleware, type, data }: RegistryParams): Promise<{
         header: {
             key: string;
@@ -58,6 +87,13 @@ export default class Actions {
             params?: undefined;
         };
     }>;
+    /**
+     * @method ServerAction
+     * @description Entry point for Server-side actions (e.g., Next.js Server Actions).
+     * It checks against server-specific policies before executing.
+     * @param {RegistryParams} params - The request payload.
+     * @returns {Promise<Object>} The standardized response or a 404 error if the action is restricted by policy.
+     */
     ServerAction({ system, middleware, type, data }: RegistryParams): Promise<{
         header: {
             key: string;
@@ -95,6 +131,13 @@ export default class Actions {
             params?: undefined;
         };
     }>;
+    /**
+     * @method APIAction
+     * @description Entry point for REST API requests.
+     * It checks against API-specific policies to prevent unauthorized access to sensitive endpoints.
+     * @param {RegistryParams} params - The request payload.
+     * @returns {Promise<Object>} The standardized response or a 404 error if the action is restricted by policy.
+     */
     APIAction({ system, middleware, type, data }: RegistryParams): Promise<{
         header: {
             key: string;

package/cjs/lib/actions.js

@@ -0,0 +1,207 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const crypto_1 = __importDefault(require("crypto"));
+const buffer_1 = require("buffer");
+/**
+ * @class Actions
+ * @description The main orchestrator of the Seishiro API. It handles the execution flow
+ * by coordinating between Registry, Message, and Policy builders across different protocols.
+ */
+class Actions {
+    registry;
+    message;
+    policy;
+    /**
+     * @constructor
+     * @param {Object} params - Configuration instances.
+     * @param {RegistryBuilder} params.registry - Instance to manage route/controller mapping.
+     * @param {MessageBuilder} params.message - Instance to handle localized error/response messages.
+     * @param {PolicyBuilder} params.policy - Instance to manage security and versioning rules.
+     */
+    constructor({ registry, message, policy, }) {
+        this.registry = registry;
+        this.message = message;
+        this.policy = policy;
+    }
+    /**
+     * @method BookRegistry
+     * @description Generates an encrypted list of available API registries and application versions.
+     * This is used to securely expose allowed actions to the client side.
+     * @returns {Object} An object containing encryption metadata (iv, type_base) and the encrypted 'data' string.
+     */
+    BookRegistry() {
+        // Default Configuration
+        const algorithm = "aes-256-ctr";
+        const type_base = "hex";
+        const ivLength = 16;
+        const ivKey = crypto_1.default.randomBytes(ivLength);
+        // Dynamic Info
+        const policyInfo = this.policy.apply();
+        const registry = this.registry.apply();
+        const keyencrypt = crypto_1.default
+            .createHash("sha256")
+            .update(String(policyInfo.passkey || "").trim())
+            .digest();
+        // Data List
+        const buildRegistry = {
+            listkey: Object.keys(registry).filter((a) => !policyInfo.noaction_api.includes(a)),
+            version_now: policyInfo.version_now,
+            version_min: policyInfo.version_min,
+            version_forceupdate: policyInfo.version_forceupdate,
+        };
+        // Create Encrypted Data
+        const cipher = crypto_1.default.createCipheriv(algorithm, keyencrypt, ivKey);
+        const results = buffer_1.Buffer.concat([
+            ivKey,
+            cipher.update(JSON.stringify(buildRegistry), "utf-8"),
+            cipher.final(),
+        ]);
+        return {
+            iv_length: ivLength,
+            type_base: type_base,
+            iv: ivKey.toString(type_base),
+            data: results.toString(type_base),
+        };
+    }
+    /**
+     * @method ResponseBuilder
+     * @private
+     * @description Standardizes the response structure for all action types, handling headers, cookies, and errors.
+     * @param {any} dataRes - The raw result or error object from the controller/middleware.
+     * @param {RegistryParams["system"]} system - The system context (headers, cookies, ip, etc.) from the request.
+     * @returns {Object} A unified response object containing headers, cookies, status code, and the final data/error payload.
+     */
+    ResponseBuilder(dataRes = {}, system) {
+        const responseStatus = dataRes.error
+            ? dataRes.status || 400
+            : dataRes.status || 200;
+        const setHeaders = typeof dataRes.headers === "object" && !Array.isArray(dataRes.headers)
+            ? Object.entries(dataRes.headers).map(([key, value]) => {
+                return {
+                    key: key,
+                    value: value,
+                };
+            })
+            : [];
+        const setCookie = Array.isArray(dataRes.set_cookie)
+            ? (dataRes.set_cookie || []).filter((a) => typeof a === "object" && !Array.isArray(a) && a.key && a.value)
+            : [];
+        const rmCookie = Array.isArray(dataRes.rm_cookie)
+            ? (dataRes.rm_cookie || []).filter((a) => typeof a === "object" && !Array.isArray(a) && a.key)
+            : [];
+        const redirect = dataRes.redirect || null;
+        if (dataRes.error || !dataRes || typeof dataRes !== "object") {
+            const buildingMessage = this.message.error(dataRes.error || "system:no-response-sending", []);
+            return {
+                header: setHeaders,
+                set_cookie: setCookie,
+                rm_cookie: rmCookie,
+                status: responseStatus,
+                redirect: redirect,
+                error: dataRes.error || "system:no-response-sending",
+                response: {
+                    status: responseStatus,
+                    message: buildingMessage.message,
+                    protocol: buildingMessage.protocol,
+                    context: buildingMessage.context,
+                    params: buildingMessage.params,
+                },
+            };
+        }
+        return {
+            header: setHeaders,
+            set_cookie: setCookie,
+            rm_cookie: rmCookie,
+            status: responseStatus,
+            redirect: redirect,
+            error: null,
+            response: {
+                status: responseStatus,
+                data: dataRes.data || {},
+            },
+        };
+    }
+    /**
+     * @method SystemAction
+     * @description The core execution engine that processes controllers and middlewares.
+     * @param {RegistryParams} params - The request payload containing system info, type, data, and optional middleware state.
+     * @returns {Promise<Object>} A promise that resolves to a standardized response object via ResponseBuilder.
+     */
+    async SystemAction({ system, middleware = {}, type, data }) {
+        try {
+            const showregistry = this.registry;
+            const getregistry = showregistry.get(type || "");
+            if (!getregistry) {
+                return this.ResponseBuilder({
+                    error: "system:no-registry",
+                    status: 404,
+                }, system);
+            }
+            if (Array.isArray(getregistry)) {
+                const middlewareExecuted = await getregistry[0]({
+                    system,
+                    middleware,
+                    type,
+                    data,
+                });
+                const responsesMiddleware = this.ResponseBuilder(middlewareExecuted, system);
+                const executedResponse = await getregistry[1]({
+                    system,
+                    middleware: responsesMiddleware,
+                    type,
+                    data,
+                });
+                return this.ResponseBuilder(executedResponse, system);
+            }
+            const executedResponse = await getregistry({
+                system,
+                middleware,
+                type,
+                data,
+            });
+            return this.ResponseBuilder(executedResponse, system);
+        }
+        catch (error) {
+            return this.ResponseBuilder({
+                error: "system:internal-server-error",
+                status: 500,
+            }, system);
+        }
+    }
+    /**
+     * @method ServerAction
+     * @description Entry point for Server-side actions (e.g., Next.js Server Actions).
+     * It checks against server-specific policies before executing.
+     * @param {RegistryParams} params - The request payload.
+     * @returns {Promise<Object>} The standardized response or a 404 error if the action is restricted by policy.
+     */
+    async ServerAction({ system, middleware, type, data }) {
+        if (this.policy.apply().noaction_server.includes(type || "")) {
+            return this.ResponseBuilder({
+                error: "system:no-registry",
+                status: 404,
+            }, system);
+        }
+        return this.SystemAction({ system, middleware, type, data });
+    }
+    /**
+     * @method APIAction
+     * @description Entry point for REST API requests.
+     * It checks against API-specific policies to prevent unauthorized access to sensitive endpoints.
+     * @param {RegistryParams} params - The request payload.
+     * @returns {Promise<Object>} The standardized response or a 404 error if the action is restricted by policy.
+     */
+    async APIAction({ system, middleware, type, data }) {
+        if (this.policy.apply().noaction_api.includes(type || "")) {
+            return this.ResponseBuilder({
+                error: "system:no-registry",
+                status: 404,
+            }, system);
+        }
+        return this.SystemAction({ system, middleware, type, data });
+    }
+}
+exports.default = Actions;

package/cjs/lib/message.d.ts

@@ -0,0 +1,69 @@
+import type { MessageKey, MessageValue, MessageLang, MessageLogic, MessageLogicLang, MessageErrorContext, MessageErrorContextOpt, MessageErrorContextSlug } from "../types/message.type";
+/**
+ * @class MessageBuilder
+ * @description Handles multi-language response messages, error formatting, and dynamic template replacement.
+ * It allows the application to return consistent, localized messages across different platforms.
+ */
+export default class MessageBuilder {
+    private message_build_lang;
+    private message_logic;
+    /**
+     * @constructor
+     * @param {MessageLang} [language="en"] - The default language code (e.g., 'en', 'id').
+     * It will be sanitized to a 2-character lowercase string.
+     */
+    constructor(language?: MessageLang);
+    /**
+     * @method set
+     * @description Registers a specific message template for the current active language.
+     * @param {MessageKey} key - The unique identifier for the message.
+     * @param {MessageValue} value - The message string (supports {{variable}} placeholders).
+     * @throws {Error} If key or value is not a string.
+     */
+    set(key: MessageKey, value: MessageValue): void;
+    /**
+     * @method get
+     * @description Retrieves a raw message template based on the key and language.
+     * Falls back to the default language if the requested language is not found.
+     * @param {MessageKey} [key=""] - The message identifier to look up.
+     * @param {MessageLang} [lang=this.message_build_lang] - Optional language override.
+     * @returns {MessageValue} The raw message string or a fallback indicator if not found.
+     */
+    get(key?: MessageKey, lang?: MessageLang): MessageValue;
+    /**
+     * @method errorMessage
+     * @description Processes a template by replacing {{key}} placeholders with actual values.
+     * @param {MessageErrorContextSlug} [errorSlug=""] - The message key/slug.
+     * @param {MessageErrorContextOpt} [errorOpt={}] - Object containing key-value pairs for replacement.
+     * @param {MessageLang} [lang=this.message_build_lang] - The language to use.
+     * @returns {string} The fully formatted message string.
+     */
+    errorMessage(errorSlug?: MessageErrorContextSlug, errorOpt?: MessageErrorContextOpt, lang?: MessageLang): string;
+    /**
+     * @method error
+     * @description Parses a complex error string (protocol:slug|slug) and returns a structured error object.
+     * @param {MessageErrorContext} [errorStr=""] - The raw error string (e.g., "auth:user-not-found").
+     * @param {MessageErrorContextOpt[]} [errorOpts=[]] - Array of option objects for multiple slugs.
+     * @param {MessageLang} [lang=this.message_build_lang] - The target language.
+     * @returns {Object} Structured error containing protocol, context array, params, and the final joined message.
+     */
+    error(errorStr?: MessageErrorContext, errorOpts?: MessageErrorContextOpt[], lang?: MessageLang): {
+        protocol: string;
+        context: string[];
+        params: object[];
+        message: string;
+    };
+    /**
+     * @method apply
+     * @description Returns the entire compiled message logic object.
+     * @returns {MessageLogicLang} The internal storage of languages and their messages.
+     */
+    apply(): MessageLogicLang;
+    /**
+     * @method use
+     * @description Merges messages from another MessageBuilder instance or a plain object into the current one.
+     * @param {MessageBuilder | MessageLogic} input - The source of new messages.
+     * @throws {Error} If the input type is invalid.
+     */
+    use(input: MessageBuilder | MessageLogic): void;
+}

package/cjs/lib/message.js

@@ -0,0 +1,156 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const format_key_1 = __importDefault(require("../utils/format-key"));
+const message_1 = require("../constants/message");
+/**
+ * @class MessageBuilder
+ * @description Handles multi-language response messages, error formatting, and dynamic template replacement.
+ * It allows the application to return consistent, localized messages across different platforms.
+ */
+class MessageBuilder {
+    message_build_lang = "";
+    message_logic = {};
+    /**
+     * @constructor
+     * @param {MessageLang} [language="en"] - The default language code (e.g., 'en', 'id').
+     * It will be sanitized to a 2-character lowercase string.
+     */
+    constructor(language = "en") {
+        this.message_build_lang = String(language || "en")
+            .toLowerCase()
+            .replace(/[^a-z]/g, "")
+            .slice(0, 2);
+        this.message_logic = {};
+    }
+    /**
+     * @method set
+     * @description Registers a specific message template for the current active language.
+     * @param {MessageKey} key - The unique identifier for the message.
+     * @param {MessageValue} value - The message string (supports {{variable}} placeholders).
+     * @throws {Error} If key or value is not a string.
+     */
+    set(key, value) {
+        const keyStr = (0, format_key_1.default)(key);
+        if (typeof value !== "string") {
+            throw new Error("Message value is only type string!");
+        }
+        if (typeof key !== "string") {
+            throw new Error("Message key is only type string!");
+        }
+        if (!this.message_logic[this.message_build_lang]) {
+            this.message_logic[this.message_build_lang] = {};
+        }
+        this.message_logic[this.message_build_lang][keyStr] = String(value).trim();
+    }
+    /**
+     * @method get
+     * @description Retrieves a raw message template based on the key and language.
+     * Falls back to the default language if the requested language is not found.
+     * @param {MessageKey} [key=""] - The message identifier to look up.
+     * @param {MessageLang} [lang=this.message_build_lang] - Optional language override.
+     * @returns {MessageValue} The raw message string or a fallback indicator if not found.
+     */
+    get(key = "", lang = this.message_build_lang) {
+        const keyStr = (0, format_key_1.default)(key);
+        let langSupport = lang;
+        // Not Language On Logic
+        if (!this.message_logic[langSupport]) {
+            console.warn("[Debugging Message]: Language not found on logic, using default language!");
+            if (this.message_logic[message_1.DefaultLanguage]) {
+                langSupport = message_1.DefaultLanguage;
+            }
+            else {
+                langSupport = Object.keys(this.message_logic || {})[0];
+            }
+        }
+        if (!this.message_logic[langSupport]) {
+            console.warn("[Debugging Message]: Language or variable not found on logic!");
+            return String(`[!NoneVariable ${keyStr}]`);
+        }
+        // Return
+        return String(this.message_logic[langSupport][keyStr] || "").trim();
+    }
+    /**
+     * @method errorMessage
+     * @description Processes a template by replacing {{key}} placeholders with actual values.
+     * @param {MessageErrorContextSlug} [errorSlug=""] - The message key/slug.
+     * @param {MessageErrorContextOpt} [errorOpt={}] - Object containing key-value pairs for replacement.
+     * @param {MessageLang} [lang=this.message_build_lang] - The language to use.
+     * @returns {string} The fully formatted message string.
+     */
+    errorMessage(errorSlug = "", errorOpt = {}, lang = this.message_build_lang) {
+        let messageContext = this.get(errorSlug, lang);
+        Object.keys(errorOpt || {}).forEach((keys) => {
+            const values = errorOpt[keys] || "";
+            const pattern = new RegExp(`{{${keys}}}`, "g");
+            messageContext = messageContext.replace(pattern, values);
+        });
+        return messageContext;
+    }
+    /**
+     * @method error
+     * @description Parses a complex error string (protocol:slug|slug) and returns a structured error object.
+     * @param {MessageErrorContext} [errorStr=""] - The raw error string (e.g., "auth:user-not-found").
+     * @param {MessageErrorContextOpt[]} [errorOpts=[]] - Array of option objects for multiple slugs.
+     * @param {MessageLang} [lang=this.message_build_lang] - The target language.
+     * @returns {Object} Structured error containing protocol, context array, params, and the final joined message.
+     */
+    error(errorStr = "", errorOpts = [], lang = this.message_build_lang) {
+        const [protocol, ...messages] = String(errorStr || "").split(":");
+        const messageContext = String(messages.join(":")).split("|");
+        const messageArrayCtx = messageContext
+            .map((errorSlug, key) => {
+            const getOpt = errorOpts[key];
+            return this.errorMessage(errorSlug, getOpt, lang);
+        })
+            .join(", ");
+        return {
+            protocol: (0, format_key_1.default)(protocol),
+            context: messageContext,
+            params: errorOpts,
+            message: messageArrayCtx,
+        };
+    }
+    /**
+     * @method apply
+     * @description Returns the entire compiled message logic object.
+     * @returns {MessageLogicLang} The internal storage of languages and their messages.
+     */
+    apply() {
+        return this.message_logic;
+    }
+    /**
+     * @method use
+     * @description Merges messages from another MessageBuilder instance or a plain object into the current one.
+     * @param {MessageBuilder | MessageLogic} input - The source of new messages.
+     * @throws {Error} If the input type is invalid.
+     */
+    use(input) {
+        if (input instanceof MessageBuilder) {
+            const otherLogic = input.apply();
+            for (const lang in otherLogic) {
+                if (Object.prototype.hasOwnProperty.call(otherLogic, lang)) {
+                    const messages = otherLogic[lang];
+                    if (!this.message_logic[lang]) {
+                        this.message_logic[lang] = {};
+                    }
+                    Object.assign(this.message_logic[lang], messages);
+                }
+            }
+        }
+        else if (typeof input === "object" && input !== null) {
+            for (const key in input) {
+                if (Object.prototype.hasOwnProperty.call(input, key)) {
+                    this.set(key, input[key]);
+                }
+            }
+        }
+        else {
+            throw new Error('The "use" input must be a MessageBuilder or mapping object!');
+        }
+    }
+}
+exports.default = MessageBuilder;

package/cjs/lib/policy.d.ts

@@ -0,0 +1,70 @@
+import { PolicyNoActionAPIAction, PolicyNoActionServerAction, PolicyNoActionKey, PolicyNoActionBase } from "../types/policy.type";
+/**
+ * @class PolicyBuilder
+ * @description Manages application policies including security passkeys, version control,
+ * and protocol-specific action restrictions (Gatekeeping).
+ */
+export default class PolicyBuilder {
+    private passkey;
+    private version_now;
+    private version_min;
+    private version_forceupdate;
+    private noaction_api;
+    private noaction_server;
+    /**
+     * @constructor
+     * @param {Object} config - The policy configuration.
+     * @param {string} config.passkey - Secret key used for registry encryption (SHA-256).
+     * @param {string} config.version_now - The current stable version of the application.
+     * @param {string} config.version_min - The minimum required version for clients to operate.
+     * @param {boolean} [config.version_forceupdate=true] - Flag to indicate if clients below version_min must update.
+     * @throws {Error} If passkey, version_now, or version_min is missing.
+     */
+    constructor({ passkey, version_now, version_min, version_forceupdate, }: {
+        passkey: string;
+        version_now: string;
+        version_min: string;
+        version_forceupdate?: boolean;
+    });
+    /**
+     * @method noaction
+     * @description Restricts specific action types from being accessed via certain protocols.
+     * @param {PolicyNoActionKey} [type=""] - The registry key/action type to restrict.
+     * @param {PolicyNoActionBase} [action=[]] - Array of protocols to block ('server-action' or 'api-action').
+     * @throws {Error} If the protocol type is invalid or the key is not a string.
+     */
+    noaction(type?: PolicyNoActionKey, action?: PolicyNoActionBase): void;
+    /**
+     * @method compareVersions
+     * @private
+     * @description Compares two semantic version strings to determine their order.
+     * @param {string} v1 - First version string.
+     * @param {string} v2 - Second version string.
+     * @returns {number} 1 if v1 > v2, -1 if v1 < v2, and 0 if they are equal.
+     */
+    private compareVersions;
+    /**
+     * @method version_info
+     * @description Checks a provided version against the minimum and current version requirements.
+     * @param {string} [version=""] - The version string to validate (usually from the client).
+     * @returns {Object} An object containing upgrade flags and version compatibility status.
+     */
+    version_info(version?: string): {
+        info_upgrade: boolean;
+        is_version_min: boolean;
+        is_version_now: boolean;
+    };
+    /**
+     * @method apply
+     * @description Retrieves the compiled policy configuration.
+     * @returns {Object} All policy settings including restricted actions and versioning data.
+     */
+    apply(): {
+        passkey: string;
+        version_now: string;
+        version_min: string;
+        version_forceupdate: boolean;
+        noaction_api: PolicyNoActionAPIAction;
+        noaction_server: PolicyNoActionServerAction;
+    };
+}