@docstack/client 0.0.1

package/lib/core/index.d.ts

@@ -0,0 +1,176 @@
+import ClientStack from './stack';
+import Class from "./class";
+import Domain from './domain';
+import { Trigger } from "./trigger/index";
+import { JobEngine } from "./job-engine/index";
+import Attribute from './attribute';
+import { AttributeType, ClientCredentials, StackConfig } from "@docstack/shared";
+/**
+ * The main entry point for the DocStack client library.
+ *
+ * DocStack manages multiple {@link ClientStack} instances and provides
+ * a unified interface for database operations, authentication, and
+ * class/attribute creation.
+ *
+ * The client emits a `ready` event when all stacks are initialized.
+ *
+ * @example
+ * ```typescript
+ * // Initialize DocStack with a single database
+ * const docstack = new DocStack({ name: 'my-app' });
+ *
+ * // Wait for ready
+ * docstack.addEventListener('ready', async () => {
+ *     const stack = docstack.getStack('my-app');
+ *     const taskClass = await stack.getClass('Task');
+ * });
+ *
+ * // Initialize with credentials for automatic authentication
+ * const docstack = new DocStack({
+ *     name: 'my-app',
+ *     credentials: { username: 'admin', password: 'secret' }
+ * });
+ * ```
+ *
+ * @extends EventTarget
+ */
+declare class DocStack extends EventTarget {
+    /** Array of stack configurations used for initialization. */
+    private config;
+    /** Whether all stacks have been initialized and ready for use. */
+    private readyState;
+    /** The primary/default stack (first in the list). */
+    private store;
+    /** Array of all initialized ClientStack instances. */
+    stacks: ClientStack[];
+    private logger;
+    private addStack;
+    private initStacks;
+    resetAll(): Promise<void>;
+    /**
+     * Returns all initialized stacks.
+     * @returns Array of ClientStack instances
+     */
+    getStacks(): ClientStack[];
+    /**
+     * Gets a stack by its name or connection string.
+     *
+     * @param name - The stack name or connection identifier
+     * @returns The matching ClientStack, or `undefined` if not found
+     *
+     * @example
+     * ```typescript
+     * const stack = docstack.getStack('my-app');
+     * if (stack) {
+     *     const users = await stack.query('SELECT * FROM User');
+     * }
+     * ```
+     */
+    getStack: (name: string) => ClientStack;
+    /**
+     * Authenticates a user on a specific stack.
+     *
+     * @param name - The stack name to authenticate against
+     * @param credentials - The user's login credentials
+     * @returns The authentication session proof
+     * @throws Error if the stack is not found
+     *
+     * @example
+     * ```typescript
+     * const proof = await docstack.authenticateStack('my-app', {
+     *     username: 'user@example.com',
+     *     password: 'password123'
+     * });
+     * ```
+     */
+    authenticateStack(name: string, credentials: ClientCredentials): Promise<import("@docstack/shared").AuthSessionProof>;
+    /**
+     * Returns whether all stacks have been initialized.
+     * @returns `true` if ready, `false` otherwise
+     */
+    getReadyState(): boolean;
+    /**
+     * Resets all stacks and re-initializes them.
+     * Useful for testing or clearing all data.
+     */
+    reset(): Promise<void>;
+    clearConnection: (conn: string) => Promise<void>;
+    /**
+     * Exports all documents from a stack.
+     *
+     * @param stackName - The name of the stack to export
+     * @returns All documents from the stack
+     * @throws Error if the stack is not found
+     */
+    export: (stackName: string) => Promise<PouchDB.Core.AllDocsResponse<{}>>;
+    /**
+     * Creates a new Class in the specified stack.
+     *
+     * @param stackName - The name of the stack to create the class in
+     * @param name - The class name
+     * @param config - Configuration with type and description
+     * @throws Error if the stack is not found
+     *
+     * @example
+     * ```typescript
+     * await docstack.createClass('my-app', 'Product', {
+     *     type: 'class',
+     *     description: 'Product catalog items'
+     * });
+     * ```
+     */
+    createClass: (stackName: string, name: string, config: {
+        type: string;
+        description: string;
+    }) => Promise<void>;
+    /**
+     * Creates a new Attribute on a Class in the specified stack.
+     *
+     * @param stackName - The name of the stack containing the class
+     * @param className - The class to add the attribute to
+     * @param params - Attribute configuration
+     * @throws Error if the stack or class is not found
+     *
+     * @example
+     * ```typescript
+     * await docstack.createAttribute('my-app', 'Product', {
+     *     name: 'price',
+     *     type: 'number',
+     *     description: 'Product price in cents'
+     * });
+     * ```
+     */
+    createAttribute: (stackName: string, className: string, params: {
+        name: string;
+        type: AttributeType["type"];
+        description?: string;
+        config?: {};
+    }) => Promise<void>;
+    /**
+     * Creates a new DocStack client instance.
+     * Initializes all configured stacks asynchronously.
+     * Listen for the `ready` event to know when initialization is complete.
+     *
+     * @param config - One or more stack configurations
+     *
+     * @example
+     * ```typescript
+     * const docstack = new DocStack(
+     *     { name: 'primary-db' },
+     *     { name: 'backup-db' }
+     * );
+     *
+     * docstack.addEventListener('ready', () => {
+     *     console.log('All stacks ready!');
+     * });
+     * ```
+     */
+    constructor(...config: StackConfig[]);
+}
+/**
+ * Core exports from the DocStack client library.
+ *
+ * @module @docstack/client
+ */
+export { ClientStack, Trigger, Class, Attribute, Domain, JobEngine };
+export { DocStack };

package/lib/core/index.js

@@ -0,0 +1,379 @@
+// import express, {Express} from 'express'
+// import { static as exStatic } from 'express';
+// import * as dotenv from "dotenv";
+// import cors from "cors";
+// dotenv.config({ path: './.env' })
+import createlogger from "../utils/logger/index";
+// import test from '../../../server/src//utils/dbManager/test';
+// import { generateJwtKeys, generatePswKeys } from '../../../server/src/utils/crypto';
+import ClientStack from './stack';
+// import { login, JWTAuthPayload, setupAdminUser } from '../../../server/src//utils/auth';
+// import memoryAdapter from "pouchdb-adapter-memory"
+// import cookieParser from 'cookie-parser';
+// import jwt from 'jsonwebtoken';
+import Class from "./class";
+import Domain from './domain';
+import { Trigger } from "./trigger/index";
+import { JobEngine } from "./job-engine/index";
+// import AbstractClass from '../../shared/src//utils/stack/class';
+import Attribute from './attribute';
+// import { EventTarget } from 'node:events';
+// let envPath = process.env.ENVFILE || "./.env";
+// envPath = resolve(process.cwd(), envPath);
+// dotenv.config({ path: envPath });
+// [TODO] Implement DocStack.type in "remote" | "local"
+// When is remote, open a websocket (socket.io) connection to given remote
+// implement cases in each of stack methods (queries and doc creation)
+// to actually send and receive messages
+// [TODO][HARD] Think about authentication mechanism
+// Probably support same rest authentication (jwtToken)
+// but also api tokens
+// Remote connection that require auth can be opened but
+// cannot send or receive messages until authentication
+class DocStack extends EventTarget {
+    async addStack(config) {
+        let stack;
+        if (typeof config == "object" && config.name) {
+            stack = await ClientStack.create(`db-${config.name}`, {
+                // defaults to leveldb
+                // adapter: 'memory',
+                plugins: [
+                // https://www.npmjs.com/package/pouchdb-adapter-memory
+                // memoryAdapter
+                ],
+                patches: config.patches,
+                credentials: config.credentials,
+                disableCryptoEngine: config.disableCryptoEngine,
+            });
+        }
+        else if (typeof config === "string") {
+            stack = await ClientStack.create(`db-${config}`, {
+                // defaults to leveldb
+                // adapter: 'memory',
+                plugins: [
+                // https://www.npmjs.com/package/pouchdb-adapter-memory
+                // memoryAdapter
+                ]
+            });
+        }
+        if (stack) {
+            this.stacks.push(stack);
+            // let window_ = window as Window & typeof globalThis & {
+            //     stacks: ClientStack[]
+            // }
+            // if (window_.stacks) {
+            //     window_.stacks.push(stack)
+            // } 
+            return stack;
+        }
+        // await setupAdminUser();
+    }
+    async resetAll() {
+        try {
+            for (const stack of this.stacks) {
+                await stack.reset();
+            }
+        }
+        catch (e) {
+            throw new Error(e);
+        }
+    }
+    getStacks() {
+        return this.stacks;
+    }
+    async authenticateStack(name, credentials) {
+        const stack = this.getStack(name);
+        if (!stack) {
+            throw new Error(`Stack '${name}' not found`);
+        }
+        return stack.authenticate(credentials);
+    }
+    getReadyState() {
+        return this.readyState;
+    }
+    async reset() {
+        try {
+            await this.resetAll();
+            await this.initStacks(this.config);
+        }
+        catch (e) {
+            throw new Error(e);
+        }
+    }
+    constructor(...config) {
+        super();
+        //private app: Express;
+        // private dbName: string;
+        this.config = [];
+        this.stacks = [];
+        this.logger = createlogger().child({ module: "client" });
+        this.initStacks = async (configs) => {
+            // TODO: Consider changing to Promise.all for concurrency
+            for (const config of configs) {
+                const stack = await this.addStack(config);
+            }
+            this.readyState = true;
+            this.dispatchEvent(new CustomEvent("ready", {
+                detail: {
+                    stacks: this.stacks
+                }
+            }));
+        };
+        this.getStack = (name) => {
+            return this.stacks.find(s => s.name == name || s.connection == name);
+        };
+        this.clearConnection = async (conn) => {
+            const fnLogger = this.logger.child({ method: 'clearConnection' });
+            try {
+                // const conn = req.params.conn;
+                if (!conn) {
+                    throw new Error("Connection name not provided");
+                }
+                await ClientStack.clear(conn);
+                fnLogger.info('Internal database cleared');
+                // return res.status(200).json({ success: true, message: 'Internal database cleared' });
+            }
+            catch (e) {
+                throw new Error(e);
+                // return res.status(500).json({ success: false, error: 'An error occurred' });
+            }
+        };
+        this.export = async (stackName) => {
+            const stack = this.getStack(stackName);
+            if (stack) {
+                const dump = await stack.dump();
+                return dump;
+            }
+            else {
+                throw new Error(`Did not find any stack for name '${stackName}'`);
+            }
+        };
+        this.createClass = async (name, config) => {
+            const fnLogger = this.logger.child({ method: 'createClass' });
+            const { type, description } = config;
+            fnLogger.info("Args", {
+                name, config
+            });
+            try {
+                const newClass = await Class.create(this.store, name, "class", description, {});
+                fnLogger.info(`class '${name}' created successfully.`, { classModel: newClass.getModel() });
+            }
+            catch (e) {
+                throw new Error(`Error during class '${name} creation. ${e}`);
+            }
+            fnLogger.info('Class created successfully');
+        };
+        this.createAttribute = async (className, params) => {
+            const fnLogger = this.logger.child({ method: 'createAttribute' });
+            const { name, type, description, config } = params;
+            fnLogger.info(`Creating attribute for class '${className}'`, {
+                name, type, config
+            });
+            try {
+                // Loads the class object
+                let classObj = await this.store.getClass(className);
+                if (classObj) {
+                    let newAttribute = await Attribute.create(classObj, name, type, description, config);
+                    fnLogger.info(`Attribute '${name}' added to class '${className}'`, { attributeModel: newAttribute.getModel() });
+                }
+                else {
+                    throw new Error(`Failed to retrieve Class '${className}'`);
+                }
+            }
+            catch (e) {
+                fnLogger.error(`Error during attribute '${name}' creation: ${e}`);
+                throw new Error(`Error during attribute '${name}' creation: ${e}`);
+            }
+        };
+        //this.dbName = (config && config.dbName) ? config.dbName : "docstack";
+        // this.app = express();
+        this.readyState = false;
+        const fnLogger = this.logger.child({ method: "constructor" });
+        /*
+        this.app.use(logRequest)
+        // Enable CORS for all routes
+        if (process.env.NODE_ENV === 'development') {
+            logger.info("Development environment. Enabling CORS for :8080");
+            this.app.use(cors({
+                origin: 'http://localhost:8080',
+                // Replace with the origin of webpack dev server
+                methods: ['GET', 'POST'],
+                credentials: true,
+            }));
+        }
+        */
+        /*
+        // Use built-in middleware for parsing JSON and URL-encoded data
+        this.app.use(express.json());
+        this.app.use(express.urlencoded({ extended: true }));
+        this.app.use(cookieParser());
+        this.app.use((req, res, next) => {
+            if (!this.readyState) {
+                return res.status(503); // Service Unavailable.
+            }
+            // Server is ready to receive requests
+            next()
+        })
+        */
+        /*
+        this.app.use('/api/private', (req, res, next) => {
+            const token = req.cookies.jwtToken
+            if (!token) {
+                logger.error("No token provided")
+                return res.status(403).json({
+                    success: false,
+                    message: 'No token provided',
+                });
+            }
+            const secretKey = process.env.JWT_PUBLIC_KEY;
+            if (!secretKey || secretKey === '') {
+                logger.error("No secret key found")
+                return res.status(500).json({
+                    success: false,
+                    message: 'No secret key found',
+                });
+            }
+            jwt.verify(token, secretKey, async (err, payload: JWTAuthPayload) => {
+                if (err) {
+                    logger.error("Invalid token", err)
+                    return res.status(403).json({
+                        success: false,
+                        message: 'Invalid token',
+                    });
+                } else {
+                    // Check whether the session is still valid
+                    const { sessionId } = payload;
+                    const UserSessionClass = await this.store.getClass("UserSession");
+                    const sessionCards = await UserSessionClass.getCards({
+                        sessionId: { $eq: sessionId },
+                        sessionStatus: { $eq: "active" }
+                    }, null, 0, 1);
+                    if (sessionCards.length === 0) {
+                        return res.status(403).json({
+                            success: false,
+                            message: 'Session expired',
+                        });
+                    }
+                    // TODO: Consider passing the session card to the next middleware
+                    next();
+                }
+            });
+        })
+        */
+        // TODO: Serve the dashboard to a specific route, i.e.: admin 
+        // this.app.use(exStatic('./dist'));
+        // TODO: Serve the static files from the build folder
+        // of the UI application
+        // this.app.get('*', (req, res) => {
+        //     const templatePath = resolve(__dirname, './dist', 'index.html');
+        //     res.sendFile(templatePath);
+        // });
+        /*
+        this.app.post('/login', async (req, res) => {
+            try {
+                const { username, password } = req.body;
+                const { responseCode, body, token } = await login(username, password);
+                // Append also the token to the response
+                let cookieOptions = {}
+                if (process.env.NODE_ENV === 'development') {
+                    cookieOptions = { sameSite: 'None', secure: true, maxAge: 1000 * 60 * 15 };
+                    logger.warn("Development mode: setting cookie options to SameSite=None; Secure=true for JWT token");
+                } else cookieOptions = { sameSite: 'Strict', httpOnly: true, maxAge: 1000 * 60 * 15 };
+
+                res.cookie('jwtToken', token, cookieOptions);
+                return res.status(responseCode).json(body);
+            } catch (error) {
+                console.error("Error during login", error);
+                return res.status(500).json({ success: false, error: 'An error occurred' });
+            }
+        });
+        */
+        /*
+        this.app.get('/api/private/reset', async (req, res) => {
+            try {
+                await this.reset();
+                return res.status(200).json({ success: true, message: 'Internal database reset' });
+            } catch (e) {
+                return res.status(500).json({ success: false, error: 'An error occurred' });
+            }
+        });
+        */
+        /*
+        this.app.get('/api/private/clear:conn', async (req, res) => {
+            try {
+                const conn = req.params.conn;
+                if (!conn) {
+                    throw new Error("Connection name not provided");
+                }
+                await ClientStack.clear(conn);
+                return res.status(200).json({ success: true, message: 'Internal database cleared' });
+            } catch (e) {
+                logger.error("Error during database clear", e);
+                return res.status(500).json({ success: false, error: 'An error occurred' });
+            }
+        });
+        */
+        /*
+        this.app.get('/api/private/test', (req, res) => {
+            return res.status(200).json({ message: 'Hello from the server! This is a private route' });
+        });
+        */
+        /*
+        this.app.post('/api/private/create-class/:name', async (req, res) => {
+            const { name } = req.params;
+            const { type, description } = req.query;
+            logger.info("create-class - received request", {
+                params: req.params,
+                query: req.query
+            })
+
+            try {
+                const newClass = await Class.create(
+                    this.store, name, type as string, description as string
+                );
+                logger.info("create-class", `class '${name}' created successfully.`,
+                    {classModel: newClass.getModel()}
+                )
+            } catch (e) {
+                logger.error(`Error during class '${name} creation: ${e}`);
+                return res.status(500).json({ success: false, error: 'An error occurred' });
+            }
+            
+            return res.status(200).json({ success: true, message: 'Class created successfully' });
+        })
+        */
+        /*
+        this.app.put('/api/private/create-attribute/:name', async (req, res) => {
+            const className = req.params.name;
+            const { name, type, config } = req.body;
+            logger.info(`create-attribute - for class '${className}'`, {
+                name, type, config
+            });
+
+            try {
+                // Loads the class object
+                let classObj = await this.store.getClass(className);
+                let newAttribute = await Attribute.create(classObj, name, type, config);
+                logger.info(`create-attribute - Attribute '${name}' added to class '${className}'`,
+                    {attributeModel: newAttribute.getModel()}
+                );
+            } catch (e) {
+                logger.error(`Error during attribute '${name}' creation: ${e}`)
+            }
+        })
+        */
+        // const port = process.env.SERVER_PORT || 5000;
+        // const server = this.app.listen(port, () => logger.info(`Listening on port ${port}`));
+        // Procedure that should run once only
+        // can be considered "setup procedures"
+        //generatePswKeys()
+        // generateJwtKeys()
+        // Server "startup procedures"
+        // setTimeout(test, 1000)
+        this.initStacks(config);
+        this.addEventListener("ready", () => fnLogger.info("DocStack client successfully initialized"));
+    }
+}
+export { ClientStack, Trigger, Class, Attribute, Domain, JobEngine };
+export { DocStack };
+//# sourceMappingURL=index.js.map

package/lib/core/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/core/index.ts"],"names":[],"mappings":"AAAA,2CAA2C;AAC3C,gDAAgD;AAChD,oCAAoC;AACpC,2BAA2B;AAC3B,oCAAoC;AACpC,OAAO,YAAY,MAAM,uBAAuB,CAAA;AAChD,gEAAgE;AAChE,uFAAuF;AACvF,OAAO,WAAW,MAAM,SAAS,CAAC;AAClC,2FAA2F;AAC3F,qDAAqD;AACrD,4CAA4C;AAC5C,kCAAkC;AAClC,OAAO,KAAK,MAAM,SAAS,CAAC;AAC5B,OAAO,MAAM,MAAM,UAAU,CAAC;AAC9B,OAAO,EAAC,OAAO,EAAC,MAAM,iBAAiB,CAAC;AACxC,OAAO,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAC;AAC/C,mEAAmE;AACnE,OAAO,SAAS,MAAM,aAAa,CAAC;AAGpC,6CAA6C;AAE7C,iDAAiD;AACjD,6CAA6C;AAC7C,oCAAoC;AAGpC,uDAAuD;AACvD,0EAA0E;AAC1E,sEAAsE;AACtE,wCAAwC;AACxC,oDAAoD;AACpD,uDAAuD;AACvD,sBAAsB;AACtB,wDAAwD;AACxD,uDAAuD;AACvD,MAAM,QAAS,SAAQ,WAAW;IAStB,KAAK,CAAC,QAAQ,CAAC,MAAmB;QACtC,IAAI,KAA8B,CAAC;QACnC,IAAI,OAAO,MAAM,IAAI,QAAQ,IAAI,MAAM,CAAC,IAAI,EAAE,CAAC;YAC3C,KAAK,GAAG,MAAM,WAAW,CAAC,MAAM,CAAC,MAAM,MAAM,CAAC,IAAI,EAAE,EAAE;gBAClD,sBAAsB;gBACtB,qBAAqB;gBACrB,OAAO,EAAE;gBACT,uDAAuD;gBACvD,gBAAgB;iBACf;gBACD,OAAO,EAAE,MAAM,CAAC,OAAO;gBACvB,WAAW,EAAG,MAAc,CAAC,WAAW;gBACxC,mBAAmB,EAAG,MAAuB,CAAC,mBAAmB;aACpE,CAAC,CAAC;QACP,CAAC;aAAM,IAAI,OAAO,MAAM,KAAK,QAAQ,EAAE,CAAC;YACpC,KAAK,GAAG,MAAM,WAAW,CAAC,MAAM,CAAC,MAAM,MAAM,EAAE,EAAE;gBAC7C,sBAAsB;gBACtB,qBAAqB;gBACrB,OAAO,EAAE;gBACT,uDAAuD;gBACvD,gBAAgB;iBACf;aACJ,CAAC,CAAC;QACP,CAAC;QACD,IAAI,KAAK,EAAE,CAAC;YACR,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;YACxB,yDAAyD;YACzD,4BAA4B;YAC5B,IAAI;YACJ,wBAAwB;YACxB,iCAAiC;YACjC,KAAK;YACL,OAAO,KAAK,CAAC;QACjB,CAAC;QACD,0BAA0B;IAC9B,CAAC;IAgBD,KAAK,CAAC,QAAQ;QACV,IAAI,CAAC;YACD,KAAK,MAAM,KAAK,IAAI,IAAI,CAAC,MAAM,EAAE,CAAC;gBAC9B,MAAM,KAAK,CAAC,KAAK,EAAE,CAAC;YACxB,CAAC;QACL,CAAC;QAAC,OAAO,CAAM,EAAE,CAAC;YACd,MAAM,IAAI,KAAK,CAAC,CAAC,CAAC,CAAC;QACvB,CAAC;IACL,CAAC;IAEM,SAAS;QACZ,OAAO,IAAI,CAAC,MAAM,CAAC;IACvB,CAAC;IAMM,KAAK,CAAC,iBAAiB,CAAC,IAAY,EAAE,WAA8B;QACvE,MAAM,KAAK,GAAG,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC;QAClC,IAAI,CAAC,KAAK,EAAE,CAAC;YACT,MAAM,IAAI,KAAK,CAAC,UAAU,IAAI,aAAa,CAAC,CAAC;QACjD,CAAC;QACD,OAAO,KAAK,CAAC,YAAY,CAAC,WAAW,CAAC,CAAC;IAC3C,CAAC;IAEM,aAAa;QAChB,OAAO,IAAI,CAAC,UAAU,CAAC;IAC3B,CAAC;IACD,KAAK,CAAC,KAAK;QACP,IAAI,CAAC;YACD,MAAM,IAAI,CAAC,QAAQ,EAAE,CAAC;YACtB,MAAM,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;QACvC,CAAC;QAAC,OAAO,CAAM,EAAE,CAAC;YACd,MAAM,IAAI,KAAK,CAAC,CAAC,CAAC,CAAC;QACvB,CAAC;IACL,CAAC;IAgFD,YAAY,GAAG,MAAqB;QAChC,KAAK,EAAE,CAAC;QAhLZ,uBAAuB;QACvB,0BAA0B;QAClB,WAAM,GAAkB,EAAE,CAAC;QAGnC,WAAM,GAAkB,EAAE,CAAC;QACnB,WAAM,GAAW,YAAY,EAAE,CAAC,KAAK,CAAC,EAAC,MAAM,EAAE,QAAQ,EAAC,CAAC,CAAC;QAuC1D,eAAU,GAAG,KAAK,EAAE,OAAsB,EAAE,EAAE;YAClD,yDAAyD;YACzD,KAAK,MAAM,MAAM,IAAI,OAAO,EAAE,CAAC;gBAC3B,MAAM,KAAK,GAAG,MAAM,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;YAC9C,CAAC;YAED,IAAI,CAAC,UAAU,GAAG,IAAI,CAAC;YACvB,IAAI,CAAC,aAAa,CAAC,IAAI,WAAW,CAAC,OAAO,EAAE;gBACxC,MAAM,EAAE;oBACJ,MAAM,EAAE,IAAI,CAAC,MAAM;iBACtB;aACJ,CAAC,CAAC,CAAA;QACP,CAAC,CAAA;QAgBM,aAAQ,GAAG,CAAC,IAAY,EAAE,EAAE;YAC/B,OAAO,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,IAAI,IAAI,IAAI,CAAC,CAAC,UAAU,IAAI,IAAI,CAAE,CAAC;QAC1E,CAAC,CAAA;QAsBM,oBAAe,GAAG,KAAK,EAAE,IAAY,EAAE,EAAE;YAC5C,MAAM,QAAQ,GAAG,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,EAAC,MAAM,EAAE,iBAAiB,EAAC,CAAC,CAAC;YAChE,IAAI,CAAC;gBACD,gCAAgC;gBAChC,IAAI,CAAC,IAAI,EAAE,CAAC;oBACR,MAAM,IAAI,KAAK,CAAC,8BAA8B,CAAC,CAAC;gBACpD,CAAC;gBACD,MAAM,WAAW,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;gBAC9B,QAAQ,CAAC,IAAI,CAAC,2BAA2B,CAAC,CAAC;gBAC3C,wFAAwF;YAC5F,CAAC;YAAC,OAAO,CAAM,EAAE,CAAC;gBACd,MAAM,IAAI,KAAK,CAAC,CAAC,CAAC,CAAC;gBACnB,+EAA+E;YACnF,CAAC;QACL,CAAC,CAAA;QAEM,WAAM,GAAG,KAAK,EAAE,SAAiB,EAAE,EAAE;YACxC,MAAM,KAAK,GAAG,IAAI,CAAC,QAAQ,CAAC,SAAS,CAAC,CAAC;YACvC,IAAI,KAAK,EAAE,CAAC;gBACR,MAAM,IAAI,GAAG,MAAM,KAAK,CAAC,IAAI,EAAE,CAAC;gBAChC,OAAO,IAAI,CAAC;YAChB,CAAC;iBAAM,CAAC;gBACJ,MAAM,IAAI,KAAK,CAAC,oCAAoC,SAAS,GAAG,CAAC,CAAC;YACtE,CAAC;QACL,CAAC,CAAA;QAEM,gBAAW,GAAG,KAAK,EAAE,IAAY,EAAE,MAGzC,EAAE,EAAE;YACD,MAAM,QAAQ,GAAG,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,EAAC,MAAM,EAAE,aAAa,EAAC,CAAC,CAAC;YAC5D,MAAM,EAAE,IAAI,EAAE,WAAW,EAAE,GAAG,MAAM,CAAC;YACrC,QAAQ,CAAC,IAAI,CAAC,MAAM,EAAE;gBAClB,IAAI,EAAE,MAAM;aACf,CAAC,CAAA;YAEF,IAAI,CAAC;gBACD,MAAM,QAAQ,GAAG,MAAM,KAAK,CAAC,MAAM,CAC/B,IAAI,CAAC,KAAK,EAAE,IAAI,EAAE,OAAO,EAAE,WAAqB,EAChD,EAAE,CACL,CAAC;gBACF,QAAQ,CAAC,IAAI,CAAC,UAAU,IAAI,yBAAyB,EACjD,EAAC,UAAU,EAAE,QAAQ,CAAC,QAAQ,EAAE,EAAC,CACpC,CAAA;YACL,CAAC;YAAC,OAAO,CAAM,EAAE,CAAC;gBACd,MAAM,IAAI,KAAK,CAAC,uBAAuB,IAAI,cAAc,CAAC,EAAE,CAAC,CAAC;YAClE,CAAC;YAED,QAAQ,CAAC,IAAI,CAAC,4BAA4B,CAAC,CAAC;QAChD,CAAC,CAAA;QAEM,oBAAe,GAAG,KAAK,EAAE,SAAiB,EAAE,MAElD,EAAE,EAAE;YACD,MAAM,QAAQ,GAAG,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,EAAC,MAAM,EAAE,iBAAiB,EAAC,CAAC,CAAC;YAChE,MAAM,EAAE,IAAI,EAAE,IAAI,EAAE,WAAW,EAAE,MAAM,EAAE,GAAG,MAAM,CAAC;YACnD,QAAQ,CAAC,IAAI,CAAC,iCAAiC,SAAS,GAAG,EAAE;gBACzD,IAAI,EAAE,IAAI,EAAE,MAAM;aACrB,CAAC,CAAC;YAEH,IAAI,CAAC;gBACD,yBAAyB;gBACzB,IAAI,QAAQ,GAAG,MAAM,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,SAAS,CAAC,CAAC;gBACpD,IAAI,QAAQ,EAAE,CAAC;oBACX,IAAI,YAAY,GAAG,MAAM,SAAS,CAAC,MAAM,CAAC,QAAQ,EAAE,IAAI,EAAE,IAAI,EAAE,WAAW,EAAE,MAAM,CAAC,CAAC;oBACrF,QAAQ,CAAC,IAAI,CAAC,cAAc,IAAI,qBAAqB,SAAS,GAAG,EAC7D,EAAC,cAAc,EAAE,YAAY,CAAC,QAAQ,EAAE,EAAC,CAC5C,CAAC;gBACN,CAAC;qBAAM,CAAC;oBACJ,MAAM,IAAI,KAAK,CAAC,6BAA6B,SAAS,GAAG,CAAC,CAAC;gBAC/D,CAAC;YAEL,CAAC;YAAC,OAAO,CAAM,EAAE,CAAC;gBACd,QAAQ,CAAC,KAAK,CAAC,2BAA2B,IAAI,eAAe,CAAC,EAAE,CAAC,CAAC;gBAClE,MAAM,IAAI,KAAK,CAAC,2BAA2B,IAAI,eAAe,CAAC,EAAE,CAAC,CAAC;YACvE,CAAC;QACL,CAAC,CAAA;QAIG,uEAAuE;QACvE,wBAAwB;QACxB,IAAI,CAAC,UAAU,GAAG,KAAK,CAAC;QACxB,MAAM,QAAQ,GAAG,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,EAAC,MAAM,EAAE,aAAa,EAAC,CAAC,CAAC;QAE5D;;;;;;;;;;;;UAYE;QACF;;;;;;;;;;;;UAYE;QACF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;UA4CE;QACF,8DAA8D;QAC9D,oCAAoC;QAEpC,qDAAqD;QACrD,wBAAwB;QACxB,oCAAoC;QACpC,uEAAuE;QACvE,kCAAkC;QAClC,MAAM;QAEN;;;;;;;;;;;;;;;;;;;UAmBE;QAEF;;;;;;;;;UASE;QACF;;;;;;;;;;;;;;UAcE;QACF;;;;UAIE;QACF;;;;;;;;;;;;;;;;;;;;;;;UAuBE;QACF;;;;;;;;;;;;;;;;;;;UAmBE;QACF,gDAAgD;QAEhD,wFAAwF;QAExF,sCAAsC;QACtC,uCAAuC;QACvC,mBAAmB;QACnB,oBAAoB;QAEpB,8BAA8B;QAC9B,yBAAyB;QACzB,IAAI,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC;QACxB,IAAI,CAAC,gBAAgB,CAAC,OAAO,EAAE,GAAG,EAAE,CAAC,QAAQ,CAAC,IAAI,CAAC,0CAA0C,CAAC,CAAC,CAAC;IACpG,CAAC;CAKJ;AAED,OAAO,EAAE,WAAW,EAAE,OAAO,EAAE,KAAK,EAAE,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,CAAC;AACrE,OAAO,EAAE,QAAQ,EAAE,CAAC"}

package/lib/core/job-engine/index.d.ts

@@ -0,0 +1,110 @@
+import type ClientStack from "../stack.js";
+import type { JobModel, JobRunModel, JobTriggerType } from "@docstack/shared";
+/**
+ * Represents an executable job that can perform background tasks.
+ *
+ * Jobs are stored as documents with executable content that is verified
+ * via hash before execution. They support singleton mode (only one instance
+ * can run at a time), metadata persistence, and run history tracking.
+ *
+ * @example
+ * ```typescript
+ * // Jobs are typically executed via JobEngine
+ * const run = await stack.jobEngine.executeJob('Job-auth', {
+ *     password: 'user-password',
+ *     salt: 'user-salt'
+ * });
+ * console.log('Job result:', run.finalMetadata);
+ * ```
+ */
+export declare class Job {
+    /** The JobModel document containing job configuration and content. */
+    readonly model: JobModel;
+    /** Reference to the parent stack for database operations. */
+    private readonly stack;
+    private constructor();
+    /**
+     * Creates a validated Job instance from a JobModel document.
+     * Verifies the content hash to ensure integrity.
+     *
+     * @param model - The JobModel document from the database
+     * @param stack - The parent ClientStack instance
+     * @returns A validated Job instance
+     * @throws Error if the content hash doesn't match
+     */
+    static create(model: JobModel, stack: ClientStack): Promise<Job>;
+    /**
+     * Hydrates the job content into an executable function.
+     * The job content must define an `execute(stack, params, job)` function.
+     */
+    private hydrate;
+    private hasRunningInstance;
+    private buildRun;
+    private persistRun;
+    private persistJobMetadata;
+    /**
+     * Executes the job with optional runtime arguments.
+     *
+     * Creates a JobRun document to track execution, handles singleton logic,
+     * and persists any metadata updates from the job execution.
+     *
+     * @param runtimeArgs - Optional parameters to pass to the job
+     * @param triggerType - How the job was triggered ('manual', 'scheduled', etc.)
+     * @returns The completed JobRunModel with status and results
+     * @throws Error if the job is disabled or a singleton instance is already running
+     *
+     * @example
+     * ```typescript
+     * const run = await job.execute({ userId: 'user-123' }, 'manual');
+     * if (run.status === 'SUCCESS') {
+     *     console.log('Result:', run.finalMetadata);
+     * }
+     * ```
+     */
+    execute(runtimeArgs?: Record<string, any>, triggerType?: JobTriggerType): Promise<JobRunModel>;
+}
+/**
+ * Engine for executing background jobs in the DocStack system.
+ *
+ * The JobEngine provides a simple interface to execute jobs by their ID.
+ * Jobs are fetched from the database, validated, and executed with
+ * full run tracking and metadata persistence.
+ *
+ * @example
+ * ```typescript
+ * // Execute a job
+ * const run = await stack.jobEngine.executeJob('Job-process-data', {
+ *     batchSize: 100
+ * });
+ *
+ * console.log('Status:', run.status);
+ * console.log('Duration:', run.durationMs, 'ms');
+ * ```
+ */
+export declare class JobEngine {
+    /** Reference to the parent stack for database operations. */
+    private readonly stack;
+    /**
+     * Creates a new JobEngine instance.
+     * @param stack - The parent ClientStack instance
+     */
+    constructor(stack: ClientStack);
+    /**
+     * Executes a job by its document ID.
+     *
+     * @param jobId - The job document ID (e.g., 'Job-auth')
+     * @param runtimeArgs - Optional parameters to pass to the job
+     * @param triggerType - How the job was triggered (default: 'manual')
+     * @returns The completed JobRunModel with execution results
+     *
+     * @example
+     * ```typescript
+     * const authRun = await jobEngine.executeJob('Job-auth', {
+     *     password: 'secret',
+     *     salt: 'user-salt'
+     * });
+     * const derivedKey = authRun.finalMetadata?.derivedKey;
+     * ```
+     */
+    executeJob(jobId: string, runtimeArgs?: Record<string, any>, triggerType?: JobTriggerType): Promise<JobRunModel>;
+}