create-moost 0.4.23 → 0.5.0

package/templates/wf/src/static/wf.css

@@ -0,0 +1,135 @@
+body {
+  margin: 0;
+  min-height: 100vh;
+  font-family: sans-serif;
+  display: flex;
+  flex-direction: column;
+  justify-content: center;
+  align-items: center;
+  gap: 1em;
+  position: relative;
+  overflow: hidden;
+  /* Main gradient background */
+  background: linear-gradient(135deg, #151e38 0%, #233e88 100%);
+}
+
+/* Top-left shape overlay */
+body::before {
+  content: "";
+  position: absolute;
+  top: -10%;
+  left: -15%;
+  width: 40vw;
+  height: 40vw;
+  background: radial-gradient(circle, #213b82 20%, transparent 70%);
+  filter: blur(60px); /* Add some blur for a more ethereal effect */
+  opacity: 0.8;
+  transform: rotate(20deg);
+  z-index: -1;
+}
+
+
+/* Container (section) with glass-like effect */
+section {
+  display: flex;
+  flex-direction: column;
+  gap: 1em;
+  max-width: 400px;
+  width: 100%;
+  padding: 1.6em;
+  border-radius: 1.6em;
+  position: relative;
+  color: #fff;
+  background: rgba(40, 69, 150, .8);
+  backdrop-filter: blur(8px);
+  box-shadow: 0 0 20px rgba(0, 0, 0, 0.2);
+}
+
+h1 {
+  margin: 12px 0;
+  display: flex;
+  gap: .5em;
+  font-size: 28px;
+  justify-content: start;
+  align-items: center;
+}
+
+h1 svg {
+  width: 48px;
+  height: 48px;;
+}
+
+form {
+  display: flex;
+  flex-direction: column;
+  gap: 1em;
+}
+
+label {
+  display: flex;
+  flex-direction: column;
+  gap: 0.5em;
+  font-weight: 600;
+}
+
+/* Inputs with a subtle focus effect */
+input {
+  padding: 0.7em;
+  border: 1px solid #ccc;
+  border-radius: 0.25em;
+  transition: border-color 0.2s ease;
+  background-color: #ffffffa0;
+}
+input:focus {
+  outline: none;
+  border-color: #4758ed;
+  outline: 2px solid #4758ed;
+  background-color: #ffffff;
+}
+
+/* Modern button styling */
+button {
+  margin-top: .7em;
+  padding: 1em;
+  border: none;
+  border-radius: 0.25em;
+  cursor: pointer;
+  background-color: #4758ed;
+  color: #fff;
+  font-weight: 600;
+  transition: background-color 0.2s ease, transform 0.2s ease;
+}
+button:hover {
+  background-color: #5f6bf2;
+  transform: translateY(-1px);
+}
+button:active {
+  transform: translateY(0);
+}
+
+p {
+  margin: 0;
+  padding: 0;
+}
+
+a {
+  margin: 1em 0 0 0;
+  opacity: 0.75;
+  color: white;
+}
+
+a:hover {
+  opacity: 1;
+}
+
+a:visited {
+  color: white;
+}
+
+p.error {
+  background-color: #ff000020;
+  border: 1px solid #aa000070;
+  padding: 1em;
+  border-radius: 1em;
+  color: #ff4444;
+}

package/templates/wf/src/workflow/wf.controller.ts

@@ -0,0 +1,230 @@
+/**
+ * @file Workflow Controller for Moost Workflow Template
+ *
+ * This file defines the `WfController` class, which orchestrates the workflow
+ * steps using the Moost Workflow (MoostWf) framework. The controller manages
+ * the workflow's context, handles user inputs, sends and verifies one-time codes (OTC),
+ * updates the database, and produces the final output.
+ *
+ * **Important:** This example is a simplified demonstration. A production implementation
+ * would involve more complex logic, robust error handling, secure key management,
+ * and integration with persistent storage systems.
+ *
+ * For more information on Moost Workflows, visit: https://moost.org/wf/
+ */
+
+import {
+  Step,
+  Workflow,
+  WorkflowParam,
+  WorkflowSchema,
+} from "@moostjs/event-wf";
+import { Controller, EventLogger, Injectable, InjectEventLogger } from "moost";
+
+import type {
+  TWfExampleContext,
+  TWfExampleInput,
+  TWfExampleInputSchema,
+} from "./wf.types";
+import { wfInputsSchema } from "./wf.types";
+
+/**
+ * `WfController` manages the workflow steps for the example workflow "wf-example".
+ *
+ * It handles user inputs, conditional steps based on context, sending and checking
+ * one-time codes, updating the database, and generating the final output greeting.
+ */
+@Injectable("FOR_EVENT")
+@Controller()
+export class WfController {
+  /**
+   * The workflow context that holds all necessary data throughout the workflow lifecycle.
+   *
+   * @type {TWfExampleContext}
+   */
+  @WorkflowParam("context")
+  ctx!: TWfExampleContext;
+
+  /**
+   * Defines the entry point for the workflow "wf-example" and its schema.
+   *
+   * The workflow schema outlines the sequence of steps and any conditional logic
+   * based on the workflow context.
+   *
+   * **Workflow Steps:**
+   * 1. `inputs` - Collect user inputs.
+   * 2. `get_supervisor_email` - Conditionally collect supervisor email if age < 18.
+   * 3. `send_otc` - Send a one-time code to the user's email.
+   * 4. `check_otc` - Verify the received one-time code.
+   * 5. `update_db` - Update the database with the user's information.
+   * 6. `output` - Generate a greeting message.
+   *
+   * **Note:** This workflow schema is a simplified demonstration. A production workflow
+   * would require more comprehensive validation, error handling, and possibly additional steps.
+   */
+  @Workflow("wf-example")
+  @WorkflowSchema<TWfExampleContext>([
+    "inputs",
+    { id: "get_supervisor_email", condition: (ctx) => (ctx.age ?? 0) < 18 },
+    "send_otc",
+    "check_otc",
+    "update_db",
+    "output",
+  ])
+  entry() {
+    // Entry point for the workflow. The actual implementation is managed by MoostWf.
+  }
+
+  /**
+   * Handles the "inputs" step of the workflow.
+   *
+   * This step collects user inputs such as name, email, password, and age. It validates
+   * that all required fields are provided. If any fields are missing, it prompts the user
+   * to provide the necessary inputs.
+   *
+   * @param {TWfExampleInput} [input] - The input data provided by the user.
+   * @returns {TWfExampleInputSchema | void} - Returns input schema requirements if validation fails.
+   */
+  @Step("inputs")
+  inputs(@WorkflowParam("input") input?: TWfExampleInput) {
+    // Validate required inputs: name, email, password, age
+    if (!input?.name || !input.email || !input.password || !input.age) {
+      console.log({ input });
+      return this.getInputsRequired({
+        fields: ["name", "email", "password", "age"],
+        values: input,
+        errorMessage: input ? "Please fill in all the fields" : "",
+      });
+    }
+
+    // Populate the workflow context with validated inputs
+    this.ctx.name = input.name as string;
+    this.ctx.email = input.email as string;
+    this.ctx.password = input.password as string;
+    this.ctx.age = input.age as number;
+  }
+
+  /**
+   * Handles the "get_supervisor_email" step of the workflow.
+   *
+   * This step is conditionally executed if the user's age is below 18. It collects
+   * the supervisor's email address to ensure that an underage user has appropriate oversight.
+   *
+   * @param {TWfExampleInput} [input] - The input data provided by the user.
+   * @returns {TWfExampleInputSchema | void} - Returns input schema requirements if validation fails.
+   */
+  @Step("get_supervisor_email")
+  supervisorEmail(@WorkflowParam("input") input?: TWfExampleInput) {
+    // Validate supervisorEmail input for underage users
+    if (!input?.supervisorEmail) {
+      return this.getInputsRequired({
+        message: "Underage person must input supervisor email",
+        fields: ["supervisorEmail"],
+        values: input,
+      });
+    }
+  }
+
+  /**
+   * Handles the "send_otc" step of the workflow.
+   *
+   * This step generates a one-time code (OTC) and logs its dispatch. In a real-world
+   * scenario, the OTC would be sent to the user's email address.
+   *
+   * @param {EventLogger} logger - The event logger instance for logging purposes.
+   */
+  @Step("send_otc")
+  sendOtc(@InjectEventLogger() logger: EventLogger) {
+    // Generate a simple 4-digit one-time code (OTC)
+    this.ctx.otcSent = `0000${String(Math.random() * 9999)}`.slice(-4);
+    logger.log(`OTC sent: ${this.ctx.otcSent}`);
+    // **Note:** In production, send the OTC via a secure channel (e.g., email or SMS)
+  }
+
+  /**
+   * Handles the "check_otc" step of the workflow.
+   *
+   * This step verifies that the OTC received from the user matches the one sent.
+   * If the OTC is invalid or missing, it prompts the user to re-enter it.
+   *
+   * @param {TWfExampleInput} [input] - The input data provided by the user.
+   * @returns {TWfExampleInputSchema | void} - Returns input schema requirements if validation fails.
+   */
+  @Step("check_otc")
+  check(@WorkflowParam("input") input?: TWfExampleInput) {
+    // Validate the received OTC against the sent OTC
+    if (!input?.otcReceived || input.otcReceived !== this.ctx.otcSent) {
+      return this.getInputsRequired({
+        message: "One Time Code has been sent (check logs)",
+        fields: ["otcReceived"],
+        values: input,
+        errorMessage: input?.otcReceived ? "OTC is invalid" : "",
+      });
+    }
+    this.ctx.otcReceived = input.otcReceived;
+  }
+
+  /**
+   * Handles the "update_db" step of the workflow.
+   *
+   * This step is responsible for updating the database with the user's information.
+   * In this demonstration, the implementation is left as a placeholder.
+   *
+   * **Note:** In a production environment, implement secure and reliable database operations here.
+   */
+  @Step("update_db")
+  updateDb() {
+    // Placeholder for database update logic
+    // **Example:** Save user information to the database
+    // this.database.saveUser(this.ctx);
+  }
+
+  /**
+   * Handles the "output" step of the workflow.
+   *
+   * This final step generates a greeting message for the user based on the collected data.
+   */
+  @Step("output")
+  outputs() {
+    this.ctx.greeting = `Welcome ${this.ctx.name}!`;
+  }
+
+  /**
+   * Generates the required input schema based on the specified options.
+   *
+   * This helper method constructs the input schema required to prompt the user for
+   * necessary inputs. It filters the predefined `wfInputsSchema` based on the
+   * specified fields and populates them with existing values from the workflow context.
+   *
+   * @param {Object} options - Configuration options for generating input schema.
+   * @param {string} [options.message] - An optional message to display on the input form.
+   * @param {Array<keyof TWfExampleContext>} options.fields - The fields to include in the input form.
+   * @param {TWfExampleInput} [options.values] - The current input values to pre-populate the form.
+   * @param {string} [options.errorMessage] - An optional error message to display if validation fails.
+   * @returns {Object} An object containing the `inputRequired` schema.
+   */
+  getInputsRequired(options: {
+    message?: string;
+    fields: Array<keyof TWfExampleContext>;
+    values?: TWfExampleInput;
+    errorMessage?: string;
+  }): { inputRequired: TWfExampleInputSchema } {
+    const inputs = [] as TWfExampleInputSchema["inputs"];
+    for (const field of options.fields) {
+      const schema = wfInputsSchema.find((f) => f.name === field);
+      if (schema) {
+        inputs.push({
+          ...schema,
+          value: (options.values?.[field] || this.ctx[field]) as string,
+        });
+      }
+    }
+    return {
+      inputRequired: {
+        inputs,
+        message: options.message,
+        errorMessage: options.errorMessage,
+      },
+    };
+  }
+}

package/templates/wf/src/workflow/wf.encrypt.ts

@@ -0,0 +1,122 @@
+/**
+ * @file Workflow State Encryption Module
+ *
+ * This module is responsible for encrypting and decrypting the workflow state,
+ * allowing secure sharing of state data between the backend and frontend.
+ *
+ * **Important:** This example is highly simplified and is intended solely for
+ * demonstration purposes. For production use, ensure that encryption keys are
+ * managed securely and consider using more robust encryption strategies.
+ *
+ * The module utilizes AES-256-GCM for encryption, providing confidentiality
+ * and integrity of the workflow state. The encrypted state is converted to a
+ * Base64 string for easy transmission and storage.
+ *
+ * For more information on Moost Workflows, visit: https://moost.org/wf/
+ */
+
+import crypto from "crypto";
+
+import type { TWfState } from "./wf.types";
+
+/**
+ * Encryption configuration constants.
+ *
+ * - `KEY`: A randomly generated 32-byte key used for AES-256 encryption.
+ * - `ALGORITHM`: The encryption algorithm to use (AES-256-GCM).
+ * - `IV_LENGTH`: The length of the Initialization Vector (IV) in bytes.
+ *                AES-GCM recommends a 12-byte IV for optimal security.
+ */
+const KEY = crypto.randomBytes(32);
+const ALGORITHM = "aes-256-gcm";
+const IV_LENGTH = 12; // Recommended IV length for GCM
+
+/**
+ * Encrypts the given workflow state object.
+ *
+ * This function serializes the workflow state to a JSON string, encrypts it using
+ * AES-256-GCM, and returns the encrypted data as a Base64-encoded string. The IV
+ * and authentication tag are prepended to the encrypted data to ensure successful
+ * decryption.
+ *
+ * **Note:** This implementation is simplified for demonstration purposes. In a
+ * real-world scenario, manage encryption keys securely and consider key rotation.
+ *
+ * @param {TWfState} state - The workflow state object to encrypt.
+ * @returns {string} The encrypted state as a Base64-encoded string.
+ */
+export function encryptState(state: TWfState): string {
+  // Generate a random Initialization Vector (IV)
+  const iv = crypto.randomBytes(IV_LENGTH);
+
+  // Create a Cipher instance using the specified algorithm, key, and IV
+  const cipher = crypto.createCipheriv(ALGORITHM, KEY, iv);
+
+  // Convert the state object to a JSON string
+  const stateString = JSON.stringify(state);
+
+  // Encrypt the state string
+  let encrypted = cipher.update(stateString, "utf8", "hex");
+  encrypted += cipher.final("hex");
+
+  // Retrieve the authentication tag generated during encryption
+  const authTag = cipher.getAuthTag();
+
+  // Combine IV, Auth Tag, and Encrypted Data into a single Buffer
+  const encryptedBuffer = Buffer.concat([
+    iv,
+    authTag,
+    Buffer.from(encrypted, "hex"),
+  ]);
+
+  // Convert the combined Buffer to a Base64 string for transmission/storage
+  return encryptedBuffer.toString("base64");
+}
+
+/**
+ * Decrypts the given Base64-encoded encrypted state string.
+ *
+ * This function decodes the Base64 string, extracts the IV and authentication tag,
+ * and decrypts the encrypted data to retrieve the original workflow state object.
+ *
+ * **Note:** This implementation is simplified for demonstration purposes. Ensure
+ * that decryption keys are managed securely and handle potential decryption errors
+ * appropriately in production environments.
+ *
+ * @param {string} encryptedState - The encrypted workflow state as a Base64 string.
+ * @returns {TWfState} The decrypted workflow state object.
+ * @throws {Error} Throws an error if decryption fails (e.g., due to invalid data).
+ */
+export function decryptState(encryptedState: string): TWfState {
+  try {
+    // Decode the Base64-encoded string to a Buffer
+    const encryptedBuffer = Buffer.from(encryptedState, "base64");
+
+    // Extract the IV from the beginning of the Buffer
+    const iv = encryptedBuffer.subarray(0, IV_LENGTH);
+
+    // Extract the authentication tag following the IV
+    const authTag = encryptedBuffer.subarray(IV_LENGTH, IV_LENGTH + 16); // GCM auth tag is 16 bytes
+
+    // Extract the actual encrypted text following the IV and auth tag
+    const encryptedText = encryptedBuffer.subarray(IV_LENGTH + 16);
+
+    // Create a Decipher instance using the specified algorithm, key, and IV
+    const decipher = crypto.createDecipheriv(ALGORITHM, KEY, iv);
+
+    // Set the authentication tag for verification during decryption
+    decipher.setAuthTag(authTag);
+
+    // Decrypt the encrypted text
+    let decrypted = decipher.update(encryptedText, undefined, "utf8");
+    decrypted += decipher.final("utf8");
+
+    // Parse the decrypted JSON string back to the workflow state object
+    return JSON.parse(decrypted) as TWfState;
+  } catch (error) {
+    // Handle decryption errors (e.g., invalid data or tampering)
+    throw new Error(
+      `Failed to decrypt workflow state: ${(error as Error).message}`
+    );
+  }
+}

package/templates/wf/src/workflow/wf.types.ts

@@ -0,0 +1,176 @@
+/**
+ * @file Workflow Types Definition for Moost Workflow Template
+ *
+ * This file defines the TypeScript interfaces and types used to manage the workflow
+ * context, inputs, and input schemas within the Moost Workflow (MoostWf) framework.
+ * Given that MoostWf is a highly generic workflow handler, it's essential to tailor
+ * the workflow context and input schemas according to the specific use cases and
+ * application patterns of your project.
+ *
+ * The defined types include:
+ * - `TWfExampleContext`: Represents the workflow's context, storing necessary data
+ *   throughout the workflow's lifecycle.
+ * - `TWfExampleInput`: Defines the structure of inputs that the workflow accepts.
+ * - `TWfExampleInputSchemaItem` & `TWfExampleInputSchema`: Describe the schema for
+ *   input forms, detailing each input field's properties such as label, name, type,
+ *   and options.
+ * - `TWfState`: Represents the state of the workflow, derived from Moost's `TFlowOutput`.
+ *
+ * Additionally, the `wfInputsSchema` constant provides a predefined schema for workflow
+ * inputs, facilitating the generation of HTML forms for user interactions.
+ *
+ * For more information on Moost Workflows, visit: https://moost.org/wf/
+ */
+
+import { TFlowOutput } from "@moostjs/event-wf";
+
+/**
+ * Defines the structure of the workflow's context.
+ *
+ * The workflow context holds all the necessary data that persists throughout the
+ * execution of the workflow. This includes user information, authentication details,
+ * and any other relevant state required for the workflow's operations.
+ */
+export interface TWfExampleContext {
+  /** The name of the user. */
+  name?: string;
+
+  /** The email address of the user. */
+  email?: string;
+
+  /** The email address of the user's supervisor. */
+  supervisorEmail?: string;
+
+  /** Indicates whether a one-time code (OTC) has been sent. */
+  otcSent?: string;
+
+  /** The received one-time code (OTC) from the user. */
+  otcReceived?: string;
+
+  /** The user's password. */
+  password?: string;
+
+  /** The age of the user. */
+  age?: number;
+
+  /** A greeting message for the user. */
+  greeting?: string;
+}
+
+/**
+ * Defines the structure of the workflow's input.
+ *
+ * `TWfExampleInput` is a generic type that maps string keys to values of various
+ * types, including strings, numbers, undefined, or objects. This flexibility allows
+ * the workflow to handle diverse input data based on different use cases.
+ */
+export type TWfExampleInput = Record<
+  string,
+  string | number | undefined | object
+>;
+
+/**
+ * Represents a single item within the workflow's input schema.
+ *
+ * Each `TWfExampleInputSchemaItem` defines the properties of an input field
+ * that will be rendered in the HTML form. This includes the label, name, type,
+ * and any additional options for select-type inputs.
+ */
+export interface TWfExampleInputSchemaItem {
+  /** The display label for the input field. */
+  label: string;
+
+  /** The unique name identifier for the input field. */
+  name: string;
+
+  /** The type of the input field (e.g., text, number, select, password). */
+  type: "text" | "number" | "select" | "password";
+
+  /** Optional array of options for select-type input fields. */
+  options?: Array<{
+    /** The display label for the option. */
+    label: string;
+
+    /** The value associated with the option. */
+    value: string;
+  }>;
+
+  /** The default value of the input field, if any. */
+  value?: string | number;
+}
+
+/**
+ * Defines the schema for the workflow's input form.
+ *
+ * `TWfExampleInputSchema` aggregates multiple `TWfExampleInputSchemaItem` objects
+ * to define the complete structure of the input form. It may also include optional
+ * messages or error messages to be displayed to the user.
+ */
+export interface TWfExampleInputSchema {
+  /** An array of input schema items defining each form field. */
+  inputs: TWfExampleInputSchemaItem[];
+
+  /** An optional message to be displayed on the form. */
+  message?: string;
+
+  /** An optional error message to be displayed if form validation fails. */
+  errorMessage?: string;
+}
+
+/**
+ * Represents the state of the workflow.
+ *
+ * `TWfState` is derived from Moost's `TFlowOutput` and encapsulates the current
+ * state of the workflow, including the context, inputs, and input schema.
+ */
+export type TWfState = TFlowOutput<
+  TWfExampleContext,
+  TWfExampleInput,
+  TWfExampleInputSchema
+>["state"];
+
+/**
+ * Defines the input schema for the workflow's HTML form.
+ *
+ * `wfInputsSchema` is an array of `TWfExampleInputSchemaItem` objects that specify
+ * the fields to be rendered in the HTML form. This schema is used by the `Wf2HtmlPage`
+ * interceptor to generate dynamic forms based on the workflow's requirements.
+ */
+export const wfInputsSchema: TWfExampleInputSchemaItem[] = [
+  {
+    label: "Name",
+    name: "name",
+    type: "text",
+    value: undefined,
+  },
+  {
+    label: "Email",
+    name: "email",
+    type: "text",
+    value: undefined,
+  },
+  {
+    label: "Password",
+    name: "password",
+    type: "password",
+    value: undefined,
+  },
+  {
+    label: "Age",
+    name: "age",
+    type: "number",
+    value: undefined,
+  },
+  {
+    label: "One Time Code",
+    name: "otcReceived",
+    type: "text",
+    value: undefined,
+  },
+  {
+    label: "Supervisor Email",
+    name: "supervisorEmail",
+    type: "text",
+    value: undefined,
+  },
+];