@quan-erp/shared-backend-core 1.0.1

package/dist/types/0d45f5fd/9a2c73cf.d.ts

@@ -0,0 +1,365 @@
+import NodeCache from "node-cache";
+import "reflect-metadata";
+import { AppRoute } from "./1c59aca9.js";
+import { Redis } from "ioredis";
+import { Manager } from "./d453df06.js";
+import { Request, Response } from 'express';
+export declare const CACHE_METADATA_KEY = "server:cache";
+export declare const CACHE_CLIENT_METADATA_KEY = "server:inject:cache";
+export declare const CACHE_ROUTE_METADATA_KEY = "cache:route:create";
+export declare const CACHE_ROUTE_DELETE_METADATA_KEY = "cache:route:delete";
+/** Generator function that produces a single cache key from an Express request and response. */
+type CacheKeyGenerator = (req: Request, res: Response) => string;
+/** Generator function that produces an array of cache keys from an Express request and response. */
+type CacheKeysGenerator = (req: Request, res: Response) => string[];
+export declare function normalizeCacheKey(key: string | string[] | (() => string | string[]) | undefined): string[];
+export interface CacheRouteOptions {
+    /** Time-to-live in milliseconds. Defaults to 10 seconds (10000 ms) if not provided. */
+    ttl?: number;
+    /** The plugin this cache belongs to. */
+    plugin?: string;
+    /** Optional name for the cache, can be used to group or identify caches. */
+    name?: string;
+    /** Optional custom key or key generator function to store the cached value. Defaults to method + args combination. */
+    key?: string | CacheKeyGenerator;
+    /**
+     * Indicates that this cache key depends on the keys in the `dependenciesKey` array.
+     * Dependency key deletion will work only when both `dependenciesKey` and `keyToDeletePrefix` are provided.
+     */
+    dependenciesKey?: string | string[] | (() => string | string[]);
+    /**
+     * When a dependency key (provided in `dependenciesKey`) is deleted, it will also delete keys matching `keyToDeletePrefix`.
+     * Dependency key deletion will work only when both `dependenciesKey` and `keyToDeletePrefix` are provided.
+     */
+    keyToDeletePrefix?: string | string[] | (() => string | string[]);
+    /** If true, parses the cached response into a ResponseDto object. Defaults to true. */
+    parseResponseDto?: boolean;
+    /** If true, caches error responses as well (e.g., responses with 4xx or 5xx status codes). Defaults to false. */
+    cacheErrorResponseDto?: boolean;
+}
+/**
+ * Method decorator to enable caching for a specific route or method.
+ *
+ * @param options - Optional configuration for caching:
+ *   - `ttl` (number): Time-to-live in milliseconds. Defaults to 10 seconds (10000 ms) if not provided.
+ *   - `plugin` (string): The plugin this cache belongs to.
+ *   - `name` (string): Optional name for the cache, can be used to group or identify caches.
+ *   - `key` (string | CacheKeyGenerator): Optional custom key to store the cached value. Defaults to method + args combination.
+ *   - `dependenciesKey` (string | string[] | Function): Cache key(s) this cache depends on.
+ *   - `keyToDeletePrefix` (string | string[] | Function): Prefix for cache keys to delete when the dependencies are deleted. Both this and `dependenciesKey` must be provided.
+ *   - `parseResponseDto` (boolean): If true, parses the cached response into a ResponseDto object. Defaults to true.
+ *   - `cacheErrorResponseDto` (boolean): If true, caches error responses (e.g., 4xx or 5xx). Defaults to true.
+ *
+ * @returns MethodDecorator - Applies metadata to the method to enable caching behavior.
+ *
+ * @example
+ * ```ts
+ * @Controller()
+ * class MyController {
+ *   @CacheRoute({ ttl: 5000, name: "userCache", key: "userData" })
+ *   getUserData() {
+ *     return fetchUserFromDb();
+ *   }
+ * }
+ * ```
+ *
+ * Notes:
+ * - The caching metadata is stored using `Reflect.defineMetadata` with the key
+ *   `CACHE_ROUTE_METADATA_KEY` on the target method.
+ * - If `options` is not provided, defaults to `{ ttl: 10000 }`.
+ */
+export declare function CacheRoute(options?: CacheRouteOptions): MethodDecorator;
+export declare function getCacheRouteOptions(target: any, propertyKey: string | symbol): CacheRouteOptions | undefined;
+/**
+ * Method decorator to mark a route or method to delete one or more cache entries.
+ *
+ * @param keys - The cache key(s) to delete when this method is called. Can be:
+ *   - A single string key
+ *   - An array of string keys
+ *
+ * @returns MethodDecorator - Applies metadata to the method indicating which cache entries
+ *   should be removed.
+ *
+ * @example
+ * ```ts
+ * class MyController {
+ *   @DeleteCache("userCache")
+ *   clearUserCache() {
+ *     // cache with key "userCache" will be deleted after this method executes
+ *   }
+ *
+ *   @DeleteCache(["userCache", "productCache"])
+ *   clearMultipleCaches() {
+ *     // deletes both caches
+ *   }
+ * }
+ * ```
+ *
+ * Notes:
+ * - The cache deletion metadata is stored using `Reflect.defineMetadata` with the key
+ *   `CACHE_ROUTE_DELETE_METADATA_KEY` on the target method.
+ * - This decorator does not itself delete the cache; it only marks the method for
+ *   cache deletion. Actual cache removal logic should read the metadata and perform deletion.
+ */
+interface DeleteRouteCacheOption {
+    key: string[] | string | CacheKeysGenerator;
+    plugin?: string;
+    name?: string;
+}
+export declare function DeleteCacheRoute(option: DeleteRouteCacheOption): MethodDecorator;
+export declare function getDeleteCacheRouteOptions(target: any, propertyKey: string | symbol): DeleteRouteCacheOption | undefined;
+type CacheFnOptions = {
+    /** Optional name for the cache, can be used to group or identify caches. */
+    name?: string;
+    /** The plugin this cache belongs to. */
+    plugin?: string;
+    /** Custom key or key generator function to store the cached value. */
+    key: string | ((...args: any[]) => string);
+    /**
+     * Indicates that this cache key depends on the keys in the `dependenciesKey` array.
+     * Dependency key deletion will work only when both `dependenciesKey` and `keyToDeletePrefix` are provided.
+     */
+    dependenciesKey?: string | string[] | (() => string | string[]);
+    /**
+     * When a dependency key (provided in `dependenciesKey`) is deleted, it will also delete keys matching `keyToDeletePrefix`.
+     * Dependency key deletion will work only when both `dependenciesKey` and `keyToDeletePrefix` are provided.
+     */
+    keyToDeletePrefix?: string | string[] | (() => string | string[]);
+    /** Time-to-live in milliseconds. Defaults to 5 minutes (300000 ms) if not provided. */
+    ttl?: number;
+};
+type CacheFnOptionMetadata = CacheFnOptions & {
+    handlerName: string;
+};
+/**
+ * Method decorator to enable caching for a specific service function.
+ *
+ * @param option - Configuration for caching:
+ *   - `name` (string): Optional name for the cache, can be used to group or identify caches.
+ *   - `plugin` (string): The plugin this cache belongs to.
+ *   - `key` (string | Function): Custom key or generator function to store the cached value.
+ *   - `dependenciesKey` (string | string[] | Function): Cache key(s) this cache depends on.
+ *   - `keyToDeletePrefix` (string | string[] | Function): Prefix for cache keys to delete when dependencies are deleted. Both this and `dependenciesKey` must be provided.
+ *   - `ttl` (number): Time-to-live in milliseconds. Defaults to 5 minutes (300000 ms) if not provided.
+ *
+ * @returns MethodDecorator - Applies metadata to the method to enable caching behavior.
+ */
+export declare function CacheFn(option: CacheFnOptions): (target: any, propertyKey: string, descriptor: PropertyDescriptor) => void;
+export declare function getCacheFnConfigs(target: any): CacheFnOptionMetadata[] | undefined;
+type DeleteCacheOptions = {
+    /** Optional name for the cache, can be used to group or identify caches. */
+    name?: string;
+    /** The plugin this cache belongs to. */
+    plugin?: string;
+    /** Array of keys or a generator function that produces keys to delete from the cache. */
+    key: string[] | ((...args: any[]) => string[]);
+};
+type DeleteCacheFnOptionMetadata = DeleteCacheOptions & {
+    handlerName: string;
+};
+/**
+ * Method decorator to delete specified cache keys when the decorated service function is called.
+ *
+ * @param option - Configuration for cache deletion:
+ *   - `name` (string): Optional name for the cache.
+ *   - `plugin` (string): The plugin this cache belongs to.
+ *   - `key` (string[] | Function): Keys to delete or a generator function returning keys to delete.
+ *
+ * @returns MethodDecorator - Applies metadata to the method to enable cache deletion.
+ */
+export declare function DeleteCacheFn(option: DeleteCacheOptions): (target: any, propertyKey: string, descriptor: PropertyDescriptor) => void;
+export declare function getDeleteCacheFnConfigs(target: any): DeleteCacheFnOptionMetadata[] | undefined;
+/**
+ * Generates a unique cache key for a given route and HTTP request.
+ *
+ * The cache key is composed of:
+ * 1. HTTP method and route path (e.g., "GET:/users/:id")
+ * 2. URL path parameters (`req.params`) serialized as `key=value` pairs
+ * 3. Query parameters (`req.query`) serialized as `key=value` pairs
+ * 4. Request body (`req.body`) serialized to JSON for POST/PUT requests
+ *
+ * @param route - The route metadata, including method and path.
+ * @param req - The Express Request object containing params, query, and body.
+ * @returns A string that uniquely identifies the request for caching purposes.
+ *
+ * @example
+ * ```ts
+ * const key = generateRouteCacheKey(
+ *   { method: 'GET', path: '/users/:id' },
+ *   req
+ * );
+ * console.log(key); // "GET:/users/:id?id=123&active=true&{}"
+ * ```
+ *
+ * Notes:
+ * - Ensures that different query parameters or path parameters produce distinct keys.
+ * - Includes request body for methods that typically carry a payload.
+ * - The generated key can be used in caching systems like Redis or in-memory caches.
+ */
+export declare function generateRouteCacheKey(route: AppRoute, req: Request): string;
+export interface ICache {
+    set<T>(key: string, value: T, ttl?: number): Promise<void> | undefined | void;
+    get<T>(key: string): Promise<T>;
+    getWith<T>(key: string): Promise<T[]>;
+    delete(key: string): Promise<void> | undefined | void;
+    deleteWith(keys: string[]): Promise<string[]> | string[];
+    fluashall(): void | Promise<void>;
+    getRaw<T>(): T;
+    disconnect(): void;
+    /**
+     * Registers an event listener for cache events.
+     *
+     * @param props - The event configuration object.
+     * @param props.type - The type of event to listen for (e.g., 'delete' for cache invalidation).
+     * @param props.keys - The target cache keys that trigger this event when operated upon.
+     * @param props.keysToDelete - Additional keys (or a function returning keys) that should be automatically deleted when the event is triggered on the target `keys`.
+     */
+    on(props: {
+        type: 'delete';
+        keys: string[];
+        keysToDelete: string[] | (() => string[]) | (() => Promise<string[]>);
+    }): void;
+}
+export declare class InMemoryCache implements ICache {
+    private listener;
+    cache: NodeCache;
+    constructor(options?: NodeCache.Options);
+    set<T>(key: string, value: T, ttl?: number): void;
+    get<T>(key: string): Promise<T>;
+    getWith<T>(pattern: string): Promise<T[]>;
+    private _internalDelete;
+    delete(key: string): Promise<void> | undefined | void;
+    deleteWith(patterns: string[]): string[];
+    fluashall(): void;
+    getRaw(): any;
+    disconnect(): void;
+    on(props: {
+        type: "delete";
+        keys: string[];
+        keysToDelete: string[] | (() => string[]) | (() => Promise<string[]>);
+    }): void;
+    private triggerDeleteKeyListener;
+    private isEventKeyMatched;
+}
+export declare class RedisCache implements ICache {
+    private readonly redis;
+    private listener;
+    constructor(redis: Redis);
+    set(key: string, value: any, ttl?: number): Promise<void>;
+    get<T>(key: string): Promise<T>;
+    getWith<T>(pattern: string): Promise<T[]>;
+    fluashall(): Promise<void>;
+    private _internalDelete;
+    delete(key: string): Promise<void>;
+    deleteWith(patterns: string[]): Promise<string[]>;
+    on(props: {
+        type: "delete";
+        keys: string[];
+        keysToDelete: string[] | (() => string[]);
+    }): void;
+    private triggerDeleteKeyListener;
+    private isEventKeyMatched;
+    subscribe(key: string, callback: () => void): void;
+    unSubscribe(callback: () => void): void;
+    onSubscribedMessage(on: string, callback: (channel: any, message: any) => void): void;
+    publish(channel: string, message: any): void;
+    getRaw<T>(): T;
+    disconnect(): void;
+}
+export interface BaseCacheOption {
+    name?: string;
+    type: 'redis' | 'in-memory';
+    ttl?: number;
+    plugin?: string;
+}
+export interface InMemoryCacheOptions extends BaseCacheOption {
+    type: 'in-memory';
+    checkperiod: number;
+}
+export interface RedisCacheOption extends BaseCacheOption {
+    type: 'redis';
+    host: string;
+    port?: number;
+    password?: string;
+    db?: number;
+    clientType?: 'publisher' | 'subscriber';
+}
+export type CacheOptions = RedisCacheOption | InMemoryCacheOptions;
+/**
+ * Class decorator to define caching behavior for a class.
+ *
+ * Sets cache metadata on the class using `Reflect.defineMetadata`. The metadata
+ * can later be used to initialize and manage caching for the class methods or instances.
+ *
+ * @param options - Configuration options for the cache.
+ *   @property name - Optional name of the cache (default: `'default'`).
+ *   @property type - Cache backend type: `'in-memory'` or `'redis'`.
+ *   @property ttl - Default time-to-live for cache entries in milliseconds (default: 10_000ms).
+ *   @property plugin - Optional plugin identifier for multi-plugin support.
+ *
+ * In-memory cache specific:
+ *   @property checkperiod - Interval in seconds to check for expired cache entries.
+ *
+ * Redis cache specific:
+ *   @property host - Redis host (default: `'localhost'` if not provided).
+ *   @property port - Redis port (default: 6379 if not provided).
+ *   @property password - Redis password (optional).
+ *   @property db - Redis database index (optional).
+ *
+ * @example
+ * ```ts
+ * @Cache({ type: 'in-memory', name: 'userCache', checkperiod: 60, ttl: 60000 })
+ * class UserService { ... }
+ *
+ * @Cache({ type: 'redis', name: 'userCache', host: 'redis.local', port: 6379 })
+ * class UserService { ... }
+ * ```
+ *
+ * Notes:
+ * - Defaults for Redis host and port are applied if missing.
+ * - This decorator does not implement caching itself; it only attaches metadata for later use.
+ */
+export declare function Cache(options?: CacheOptions): ClassDecorator;
+export declare function getCacheConfigs(target: any): RedisCacheOption[] | undefined;
+type CacheClientOptions = {
+    plugin?: string;
+    name: string;
+};
+/**
+ * Property decorator to mark a property as a cache client reference.
+ *
+ * Attaches metadata to the property that can later be used to inject
+ * or retrieve a cache client instance from a cache manager.
+ *
+ * @param plugin - Optional plugin identifier to namespace the cache client.
+ * @param name - Name of the cache client (default: `CacheManager.DEFAULT_NAME`).
+ *
+ * @example
+ * ```ts
+ * class UserService {
+ *   @CacheClient('user-plugin', 'userCache')
+ *   cacheClient: CacheClientType;
+ * }
+ * ```
+ */
+export declare function CacheClient(plugin?: string, name?: string): PropertyDecorator;
+export declare function getCacheClientMetadata(target: any, propertyKey: string | symbol): CacheClientOptions | undefined;
+/**
+ * Central manager for cache clients within the Quan ERP kernel.
+ *
+ * Supports both high-performance in-memory caching and distributed Redis-based
+ * caching. This manager handles the lifecycle (initialization and registration)
+ * of named cache sources scoped to specific plugins.
+ */
+export declare class CacheManager extends Manager<ICache> {
+    /**
+     * Initializes a new cache source based on the provided configuration.
+     *
+     * @param cacheConfig - Configuration defining the cache type (redis/in-memory) and connection details.
+     * @param plugin - The name of the plugin context (defaults to 'default').
+     * @param name - Unique registration name for this source (defaults to 'default').
+     */
+    newCacheSource(cacheConfig: CacheOptions, plugin?: string, name?: string): Promise<void>;
+    logDebugInfo(): void;
+}
+export {};

package/dist/types/0d45f5fd/a1a2ec11.d.ts

@@ -0,0 +1,142 @@
+import { Manager, RegistryValue } from "./d453df06.js";
+import WebSocket, { WebSocketServer } from "ws";
+import http from 'http';
+export type WebsocketOptions = {
+    ssl: boolean;
+    pingpongInterval: number;
+    path: string;
+};
+export type WebsocketEvents = "open" | "message" | "close" | "error" | "ping" | "pong" | "upgrade" | "redirect" | "unexpected-response";
+export interface IWebsocket {
+    onAuthenticate(ws: WebSocket, req: http.IncomingMessage): ClientInfo | null;
+    onUpgrade(ws: WebSocket, req: http.IncomingMessage): void;
+    on(event: WebsocketEvents, client: WebsocketClient, data: any, isBinary: boolean): void;
+    onDestoryed(): void;
+}
+/**
+ * Class decorator that marks a class as a Websocket handler.
+ *
+ * Decorated classes must implement `IWebsocket`. The metadata provided
+ * specifies the endpoint path, SSL requirements, and ping/pong intervals.
+ *
+ * @param options - Configuration including the URL path and protocol settings.
+ */
+export declare function Websocket(options: WebsocketOptions): (target: any) => void;
+export declare function getWebsocketConfig(target: any): WebsocketOptions | undefined;
+/**
+ * Property decorator that injects a `WebsocketServer` instance for a specific path.
+ *
+ * The injected server provides high-level methods for broadcasting messages
+ * and sending directed events to specific connected clients.
+ *
+ * @param path - The URL path of the target websocket handler (default: 'default').
+ */
+export declare function InjectWebsocketServer(path?: string): (target: any, propertyKey: string | symbol) => void;
+export declare function getWebsocketServerInjectConfig(target: any, propertyKey: string | symbol): {
+    path: string;
+};
+export type WebsocketServer = {
+    getByClientId(clientId: string): WebsocketClient[] | null;
+    sendText(clientId: string, data: WebsocketTextEventMessage): void;
+    sendBinary(clientId: string, data: WebsocketBinaryMessage): void;
+    brocast(data: WebsocketMessage): void;
+    getAllClients(): WebsocketClient[];
+};
+export interface WebsocketMessage {
+    getMessage(): any;
+}
+export declare class WebsocketTextMessage implements WebsocketMessage {
+    data: string;
+    constructor(data: string);
+    getMessage(): string;
+}
+export declare class WebsocketTextEventMessage implements WebsocketMessage {
+    event: string;
+    payload: any;
+    constructor(event: string, payload: any);
+    static fromJson(json: string): WebsocketTextEventMessage;
+    toJson(): string;
+    getMessage(): string;
+}
+export declare class WebsocketBinaryMessage implements WebsocketMessage {
+    payload: Buffer;
+    constructor(payload: Buffer);
+    getMessage(): Buffer<ArrayBufferLike>;
+}
+/**
+ * A specialized dispatcher for incoming websocket messages.
+ *
+ * This handler categorizes incoming data into:
+ * 1. **Standard Events**: Mapping to `WebsocketEvents` like "message", "error", or "close".
+ * 2. **Structured Text Events**: Parsing JSON payloads to trigger specific logic
+ *    based on an `event` field (e.g., `{ "event": "chat_message", "data": "..." }`).
+ *
+ * The dispatcher prioritized structured text events over general message handlers when appropriate.
+ */
+export declare class WebsocketMessageHandler {
+    private event;
+    private data;
+    private isBinary;
+    private listener;
+    private textEvent;
+    constructor(event: WebsocketEvents, data: any, isBinary: boolean);
+    on(event: WebsocketEvents, callback: () => void): WebsocketMessageHandler;
+    onTextEvent(event: string, callback: () => void): WebsocketMessageHandler;
+    execute(): void;
+}
+/**
+ * Represents the identity and metadata of an authenticated websocket client.
+ * Must include at least a unique `id`.
+ */
+export type ClientInfo = {
+    id: string;
+} & Record<string, any>;
+/**
+ * A wrapper class that encapsulates an active websocket connection and its associated client metadata.
+ *
+ * This class provides a stable interface for interacting with a specific connected client,
+ * abstracting away the raw socket and providing easy access to the client's identity.
+ */
+export declare class WebsocketClient {
+    private ws;
+    private clientData;
+    constructor(ws: WebSocket, clientData?: ClientInfo);
+    /** @returns The raw `ws.WebSocket` instance. */
+    getWebsocket(): WebSocket;
+    /** @returns The unique identifier for this client. */
+    getClientId(): string;
+    /** @returns The full metadata associated with this client. */
+    getClientData(): ClientInfo;
+}
+type RegistryMetadata = WebsocketOptions & {
+    clients: Record<string, WebsocketClient[]>;
+    pingIntervalInstance?: NodeJS.Timer | null;
+};
+/**
+ * Orchestrator for real-time websocket communication within the Quan ERP kernel.
+ *
+ * The `WebsocketManager` handles:
+ * 1. **Handler Lifecycle**: Registration and destruction of plugin-scoped websocket modules.
+ * 2. **Physical Server Management**: Lazy initialization of `ws.WebSocketServer` instances based on requested paths.
+ * 3. **Connection Logic**: Managing the upgrade process, authentication triggers, and message/close event routing.
+ * 4. **Keep-Alive**: Automated ping/pong mechanism to detect and prune stale connections.
+ */
+export declare class WebsocketManager extends Manager<IWebsocket, RegistryMetadata> {
+    private websocketServers;
+    register(instance: IWebsocket, metadata?: (Partial<WebsocketOptions> & Record<string, any>) | null, plugin?: string, name?: string): void;
+    registerWebsocket(instance: IWebsocket, option: WebsocketOptions, plugin?: string): void;
+    deRegisterByScope(plugin: string, path?: string): void;
+    private initialzeServerByPath;
+    private assignWebsocketClient;
+    private removeWebsocketClient;
+    getOrCreateServer(path: string): WebSocketServer | null;
+    private cleanupWebsocketInstanceServer;
+    destoryAll(): void;
+    getAllWebsocketHandler(): ({
+        instance: IWebsocket;
+    } & WebsocketOptions)[];
+    findInstanceByPath(path: string): RegistryValue<IWebsocket, RegistryMetadata> | null;
+    getServer(path: string): WebsocketServer | null;
+    logDebugInfo(): void;
+}
+export {};

package/dist/types/0d45f5fd/a45e63d6.d.ts

@@ -0,0 +1,4 @@
+import { Manager } from "./d453df06.js";
+export type AnalyticsCallback = (url: string, timetaken: number) => void;
+export declare class AnalyticsManager extends Manager<AnalyticsCallback> {
+}

package/dist/types/0d45f5fd/a73ae28b.d.ts

@@ -0,0 +1,48 @@
+import { CorsOptions } from "cors";
+import "reflect-metadata";
+import { WebsocketOptions } from "./a1a2ec11.js";
+export interface ServerOptions {
+    name?: string;
+    port: number;
+    modules: any[];
+    cors?: boolean | CorsOptions;
+    /** Enable a /health endpoint for monitoring */
+    healthCheck?: boolean;
+    checkInterval?: number;
+    /** Enable a /readiness endpoint (for deployment or load balancer readiness) */
+    readiness?: boolean;
+    buildinModules?: any;
+    websocket?: WebsocketOptions;
+}
+/**
+ * Class decorator to define a server configuration.
+ *
+ * This decorator stores metadata about the server, such as port, modules,
+ * middleware, CORS, health checks, readiness endpoints, and websocket options.
+ *
+ * @param {ServerOptions} options - Configuration options for the server.
+ * @param {number} options.port - The port the server will listen on (default: 3000).
+ * @param {any[]} options.modules - An array of modules to load in the server.
+ * @param {boolean | CorsOptions} [options.cors] - Enable and configure CORS.
+ * @param {boolean} [options.healthCheck=true] - Enable a `/health` endpoint for monitoring.
+ * @param {number} [options.checkInterval=5000] - Interval in ms for health checks.
+ * @param {boolean} [options.readiness=true] - Enable a `/readiness` endpoint for deployment/load balancers.
+ * @param {any} [options.buildinModules=true] - Load built-in modules if set.
+ * @param {WebsocketOptions} [options.websocket] - Optional websocket configuration.
+ *
+ * @returns {ClassDecorator} A decorator that attaches server configuration metadata.
+ *
+ * @example
+ * ```ts
+ * @Server({
+ *   port: 4000,
+ *   modules: [UserModule, AuthModule],
+ *   cors: true,
+ *   healthCheck: true,
+ *   readiness: true,
+ * })
+ * class AppServer {}
+ * ```
+ */
+export declare function Server(options?: ServerOptions): ClassDecorator;
+export declare function getServerConfig(target: any): ServerOptions;

package/dist/types/0d45f5fd/b5020a96.d.ts

@@ -0,0 +1,36 @@
+import serveStatic from "serve-static";
+export declare const PLUGIN_CONFIG_KEY = "plugin:config";
+/**
+ * Configuration options for the application's plugin management system.
+ */
+export interface PluginConfigOption {
+    /**
+     * Path where installed plugins are stored.
+     * If an object is provided, custom Express static serving options can be applied.
+     */
+    installedLocalPluginPath?: string | {
+        path: string;
+        options: Pick<serveStatic.ServeStaticOptions, "maxAge" | "immutable" | "etag">;
+    };
+    /**
+     * Path to the local repository of available (not yet installed) plugins.
+     */
+    availablePluginLocalPath?: {
+        pluginServer: string;
+        localPath: string;
+    };
+    /**
+     * Filesystem path to the directory containing workflow/runner definitions.
+     */
+    runnerFlowFilePath?: string;
+}
+/**
+ * Class decorator for the root server class to configure global plugin and workflow settings.
+ *
+ * This decorator defines where the application looks for plugin code, how it serves
+ * plugin-hosted frontend assets, and where it stores automation workflow definitions.
+ *
+ * @param option - The plugin system configuration.
+ */
+export declare function PluginConfig(option?: PluginConfigOption): (target: any) => void;
+export declare function getPluginConfig(target: any): PluginConfigOption | undefined;

package/dist/types/0d45f5fd/b528e7a2.d.ts

@@ -0,0 +1,81 @@
+import { Manager } from "./d453df06.js";
+import { CoreApp } from "./d9b4a449.js";
+export interface Env {
+    all(): Record<string, Record<string, {
+        value: string;
+    } & EnvRegistryMetadata | undefined>>;
+    get(name: string): string | undefined | null;
+    set(name: string, value: string | null, options?: SetPluginEnvOptions): any;
+    sync(): Promise<void>;
+    onChanged(key: string, callback: () => void): void;
+    clear(): void;
+}
+export declare const ENV_METADATA_KEY = "env";
+/**
+ * Property decorator that injects the environment configuration manager (Env) for the current plugin.
+ *
+ * The injected `Env` object allows the plugin to:
+ * 1. **Get/Set Configs**: Read and write environment variables scoped specifically to the plugin.
+ * 2. **Persistence**: Sync configuration changes back to the database.
+ * 3. **Reactivity**: Register listeners for when specific configuration keys change.
+ *
+ * @example
+ * ```ts
+ * @Service()
+ * class MyService {
+ *   @InjectEnv()
+ *   private env: Env;
+ *
+ *   async start() {
+ *     const apiKey = this.env.get('API_KEY');
+ *     this.env.onChanged('API_KEY', () => { ... });
+ *   }
+ * }
+ * ```
+ */
+export declare function InjectEnv(): PropertyDecorator;
+export declare function getEnvInjection(target: any, propertyKey: string | symbol): boolean | undefined;
+export interface SetPluginEnvOptions {
+    sync?: boolean;
+    isPublic?: boolean;
+    isSecret?: boolean;
+}
+export interface PluginEnvManager {
+    get(key: string): string | undefined;
+    set(key: string, value: string, option: SetPluginEnvOptions): void;
+}
+export type EnvRegistryMetadata = {
+    isPublic: boolean;
+    isSecret: boolean;
+};
+export declare class PluginEnvConfigManager extends Manager<string, EnvRegistryMetadata> {
+    private app;
+    private cached;
+    private events;
+    constructor(app: CoreApp);
+    register(instance: string, metadata?: (Partial<{}> & Record<string, any>) | null, plugin?: string, name?: string): void;
+    set(plugin: string, key: string, value: string, { sync, isPublic, isSecret }: SetPluginEnvOptions): Promise<void>;
+    get(plugin: string, key: string): string | undefined;
+    getAllByPluginName(plugin: string): Record<string, Record<string, {
+        value: string;
+        isPublic: boolean;
+        isSecret: boolean;
+    }>>;
+    getAll(option?: {
+        maskSecret?: boolean;
+        includeSecret?: boolean;
+        publicOnly?: boolean;
+    }): Record<string, Record<string, {
+        value: string;
+        isPublic: boolean;
+        isSecret: boolean;
+    }>>;
+    getAllPublic(): Record<string, Record<string, string>>;
+    getPublic(plugin: string, key: string): string | null;
+    onChanged(plugin: string, key: string, callback: () => void): void;
+    reset(plugin: string): Promise<void>;
+    syncToDB(): Promise<void>;
+    loadFromDB(): Promise<void>;
+    private generateEventKey;
+    private registryToJSON;
+}