blokctl 1.2.0 → 1.4.0

package/dist/scaffold-repo/triggers/http/notes/CLI_Commands/Create_Node.md

@@ -0,0 +1,123 @@
+# 🛠 Creating a Node in `Blok`
+
+A **node** is the core component of a workflow in `Blok`. It represents a reusable function that can be executed as part of a workflow.
+
+This guide walks you through creating a **custom node** using **TypeScript**.
+
+---
+
+## 📌 Step 1: Create a Node Using the CLI
+
+To create a new node, run the following command from the **root directory** of your blok project:
+
+```bash
+npx blokctl@latest create node
+```
+
+### 📥 CLI Inputs
+
+You will be prompted to provide the following information:
+
+1. **Node Name**  
+    Enter a unique name for the node (e.g., `fetch`).
+
+2. **Select Runtime**  
+    Choose between:
+    - **TypeScript (recommended)** ✅ *(Default)*
+    - **Python3** *(Alpha version, MacOS & Linux only)*  
+    *(For this guide, select **TypeScript**.)*
+
+3. **Select Blok Type**  
+    Choose between:
+    - **Module** *(For npm-published nodes – ❌ not needed for this guide)*
+    - **Class** ✅ *(Default, for local nodes)*
+
+4. **Select Template**  
+    Choose between:
+    - **Class (recommended)** ✅ *(Default)*
+    - UI - EJS - REACTJS - TailwindCSS *(not required for this guide)*
+
+---
+
+## 📌 Step 2: Navigate to the New Node Directory
+
+Once the node is created, navigate to its directory:
+
+```bash
+cd src/nodes/fetch
+```
+
+---
+
+## 📌 Step 3: Update the Node Class Name
+
+Open the `index.ts` file inside the node directory and **update the class name** to match your node name (`Fetch` in this example):
+
+```typescript
+// Original class name
+export default class Node extends BlokService {
+     ...
+}
+
+// Updated class name
+export default class Fetch extends BlokService {
+     ...
+}
+```
+
+---
+
+## 📌 Step 4: Register the Node in the `Nodes.ts` File
+
+To make your node available in workflows, **register it inside `src/Nodes.ts`**:
+
+```typescript
+import ApiCall from "@blokjs/api-call";
+import IfElse from "@blokjs/if-else";
+import type { NodeBase } from "@blokjs/shared";
+import Fetch from "./nodes/fetch";
+
+const nodes: {
+     [key: string]: NodeBase;
+} = {
+     "@blokjs/api-call": new ApiCall(),
+     "@blokjs/if-else": new IfElse(),
+     "fetch": new Fetch()
+};
+
+export default nodes;
+```
+
+---
+
+## 📌 Step 5: Validate the Node
+
+To confirm that the new node is registered correctly:
+
+1. **Start the project**  
+    Run the following command in the project root directory:
+
+    ```bash
+    npm run dev
+    ```
+
+---
+
+## 🎯 Summary
+
+- ✅ **Created a custom node** using the CLI.  
+- ✅ **Configured the node class name** correctly.  
+- ✅ **Registered the node** inside `Nodes.ts`.  
+- ✅ **Validated the project setup**.
+
+Your node is now ready to be used in workflows! 🎉
+
+---
+
+## 🔍 Next Steps
+
+- [Context](../Core_Concepts/Context.md)
+- [Creating Workflows](../CLI_Commands/Create_Workflow.md)  
+- [Creating Custom Nodes](../CLI_Commands/Create_Node.md)  
+- [Examples](../examples.md)
+- [Index](../index.md)

package/dist/scaffold-repo/triggers/http/notes/CLI_Commands/Create_Workflow.md

@@ -0,0 +1,177 @@
+# 🚀 Creating a Workflow in blok
+
+A **workflow** in `Blok` is a structured JSON file that defines:
+
+- **A trigger** that starts the workflow execution.
+- **A sequence of steps** that execute bloks (nodes).
+- **Node configurations** that define how each step operates.
+
+---
+
+## 📌 Step 1: Create a Workflow Using the CLI
+
+To create a new workflow, run the following command:
+
+```sh
+npx blokctl@latest create workflow
+```
+
+### 🛠 CLI Inputs
+
+- **Workflow Name**: Provide a unique name for your workflow.
+- The workflow JSON file will be created inside the `workflows/json/` directory.
+
+---
+
+## 📌 Step 2: Understand the Workflow Structure
+
+A workflow consists of **three** main sections:
+
+1. **Trigger**: Defines how the workflow is executed.  
+2. **Steps**: Specifies the sequence of nodes executed in order.  
+3. **Nodes**: Configures each node used in the steps.  
+
+---
+
+## 📌 Step 3: Example Workflow (Fetching Data)
+
+Below is an example of a workflow named **"fetch-cat-facts"** that makes an HTTP request to fetch cat facts. Save this file as `workflows/json/cats.json`:
+
+```json
+{
+    "name": "fetch-cat-facts",
+    "description": "This workflow fetches random cat facts from a public API.",
+    "version": "1.0.0",
+    "trigger": {
+        "http": {
+            "method": "GET",
+            "path": "/",
+            "accept": "application/json"
+        }
+    },
+    "steps": [
+        {
+            "name": "fetch_api_data",
+            "node": "@blokjs/api-call",
+            "type": "module"
+        }
+    ],
+    "nodes": {
+        "fetch_api_data": {
+            "inputs": {
+                "url": "https://catfact.ninja/fact",
+                "method": "GET",
+                "headers": {}
+            }
+        }
+    }
+}
+```
+
+---
+
+## 📌 Step 4: Workflow Structure Breakdown
+
+### 🔹 1. **Trigger Section**
+
+The `trigger` defines how the workflow is executed:
+
+```json
+"trigger": {
+    "http": {
+        "method": "GET",
+        "path": "/",
+        "accept": "application/json"
+    }
+}
+```
+
+- **`method`**: Specifies the HTTP method (e.g., `GET`, `POST`, etc.). Use `"*"` to accept **any** method.
+- **`path`**: Defines the URL path. Supports **path parameters**:
+    - `"/:id"` → Required parameter (e.g., `/cats/123`).
+    - `"/:id?"` → Optional parameter (e.g., `/cats` or `/cats/123`).
+- **`accept`**: Defines the expected response format (`application/json` by default).
+
+---
+
+### 🔹 2. **Steps Section**
+
+The `steps` define the sequence of nodes executed in the workflow:
+
+```json
+"steps": [
+    {
+        "name": "fetch_api_data",
+        "node": "@blokjs/api-call",
+        "type": "module"
+    }
+]
+```
+
+- **`name`**: Unique name for the step.
+- **`node`**: The node to execute (e.g., `@blokjs/api-call`).
+- **`type`**: Specifies the type of node. The available options are:
+    - **`module`**: Used for nodes installed as dependencies (e.g., from npm) or nodes created using the `Class` type.
+    - **`local`**: Used for nodes created locally, typically intended for publishing to npm.
+
+---
+
+### 🔹 3. **Nodes Section**
+
+The `nodes` section configures each node used in the workflow:
+
+```json
+"nodes": {
+    "fetch_api_data": {
+        "inputs": {
+            "url": "https://catfact.ninja/fact",
+            "method": "GET",
+            "headers": {}
+        }
+    }
+}
+```
+
+- **`inputs`**: Configuration values for the node.
+    - **`url`**: API endpoint.
+    - **`method`**: HTTP method (`GET`, `POST`, etc.).
+    - **`headers`**: Optional request headers.
+
+---
+
+## 📌 Step 5: Run & Test the Workflow
+
+1. **Start the blok project**:
+
+     ```sh
+     npm run dev
+     ```
+
+2. **Test the workflow using `curl` or Postman**:
+
+     ```sh
+     curl http://localhost:4000/cats
+     ```
+
+     ✔ If everything is set up correctly, the response will contain a **random cat fact** fetched from the API. The `/cats` path corresponds to the workflow JSON file **`workflows/json/cats.json`**.
+
+---
+
+## 🎯 Summary
+
+- ✅ Workflows consist of **Triggers**, **Steps**, and **Nodes**.  
+- ✅ HTTP triggers support **method filtering (`GET`, `POST`, etc.)** and **dynamic paths (`/:id`)**.  
+- ✅ Nodes execute bloks and are configured in the **nodes section**.  
+- ✅ Workflows can be tested via `curl` or Postman.  
+
+---
+
+## 🔍 Next Steps
+
+Now that you understand workflows, explore:
+
+- [Context](../Core_Concepts/Context.md)
+- [Creating Custom Nodes](../CLI_Commands/Create_Node.md)
+- [Creating Workflows](../CLI_Commands/Create_Workflow.md)
+- [Examples](../examples.md)
+- [Index](../index.md)

package/dist/scaffold-repo/triggers/http/notes/CLI_Commands/Deployment.md

@@ -0,0 +1,69 @@
+# BlokService CLI Commands
+
+## Table of Contents
+
+---
+
+## Deploy Blok 
+
+### Syntax
+```bash
+npx blokctl deploy [options]
+```
+
+
+ Deploys a blok to the BlokServices platform, optionally building it first.
+ *
+ Options:
+ - `--name`, `-n` (string): Service name (required). Default: none.
+ - `--build` (boolean): Build before deploying. Default: false.
+ - `--directory`, `-d` (string): Source directory path. Default: Current working directory.
+ - `--help`, `-h` (boolean): Show help. Default: false.
+ *
+ Commands:
+ - `.`: Deploy from the current directory.
+
+### Examples
+
+#### Deploy with build:
+```bash
+npx blokctl deploy -n my-service --build
+```
+
+#### Deploy existing build:
+```bash
+npx blokctl deploy -n my-service -d ./build-output
+```
+
+#### Deploy from current directory:
+```bash
+npx blokctl deploy -n my-service .
+```
+
+<br />
+<br />
+<br />
+
+---
+# Build and Deploy Example
+
+#### Build and deploy workflow:
+```bash
+# Build first
+npx blokctl build -d ./src
+
+# Then deploy
+npx blokctl deploy -n my-service -d ./src
+```
+
+#### Single-command build & deploy:
+```bash
+npx blokctl deploy -n my-service --build
+```
+
+#### CI/CD Pipeline Example:
+```bash
+# In your deployment script
+npx blokctl build -d $CODE_DIR
+npx blokctl deploy -n $SERVICE_NAME -d $CODE_DIR
+```

package/dist/scaffold-repo/triggers/http/notes/Core_Concepts/Context.md

@@ -0,0 +1,156 @@
+# Understanding Context (`ctx`)
+
+In `Blok`, **Context (`ctx`)** is the primary data structure that flows between nodes in a workflow. It enables nodes to **exchange data** and maintain state throughout execution.
+
+---
+
+## 📌 Context Structure
+
+Each node in a workflow receives `ctx` as an input, which contains the following structure:
+
+```typescript
+const ctx: Context = {
+    vars: {}, // Stores dynamically generated variables
+    request: { body: {}, method: "GET", headers: {}, query: {}, params: {} }, // Incoming request details
+    response: { data: {} } // Stores processed results
+};
+```
+
+### 🔹 Breakdown of `ctx`
+
+- **`ctx.request`**: Contains all HTTP request details:
+  - `body`: The request payload (e.g., for POST, PUT requests)
+  - `method`: HTTP method (e.g., GET, POST, etc.)
+  - `headers`: Request headers
+  - `query`: Query parameters (e.g., `?key=value`)
+  - `params`: Path parameters (e.g., `/:id`)
+
+- **`ctx.response`**: Holds workflow outputs:
+  - `data`: The latest processed data from nodes
+
+- **`ctx.vars`**: Temporary workflow variables:
+  - These are **not persisted** across requests.
+  - Nodes can store variables dynamically for later use.
+
+---
+
+## 📖 Context in Workflows
+
+Context is essential for **passing data between nodes** and making dynamic decisions.
+
+### 🛠 Example: Using `ctx.request.params`
+
+In this workflow, we extract `id` from the request URL and fetch details from MongoDB:
+
+```json
+{
+    "name": "Get Movie Details",
+    "description": "Fetches a movie by ID",
+    "version": "1.0.0",
+    "trigger": {
+        "http": {
+            "method": "GET",
+            "path": "/movies/:id",
+            "accept": "application/json"
+        }
+    },
+    "steps": [
+        {
+            "name": "get-movie",
+            "node": "mongo-query",
+            "type": "local"
+        }
+    ],
+    "nodes": {
+        "get-movie": {
+            "inputs": {
+                "collection": "movies",
+                "id": "${ctx.request.params.id}"
+            }
+        }
+    }
+}
+```
+
+#### 🔹 How it Works:
+- `path: "/movies/:id"` defines a **dynamic route**.
+- The MongoDB node retrieves the movie using:
+  ```json
+  "id": "${ctx.request.params.id}"
+  ```
+  This extracts `id` from the URL (e.g., `/movies/123` → `ctx.request.params.id = 123`).
+
+---
+
+### 🛠 Example: Using `ctx.vars`
+
+This workflow **stores an API response in a variable** and **uses it in a later step**:
+
+```json
+{
+    "name": "Fetch and Process Data",
+    "description": "Stores fetched data and processes it",
+    "version": "1.0.0",
+    "trigger": {
+        "http": {
+            "method": "GET",
+            "path": "/fetch-data",
+            "accept": "application/json"
+        }
+    },
+    "steps": [
+        {
+            "name": "fetch-data",
+            "node": "@blokjs/api-call",
+            "type": "module",
+            "set_var": true
+        },
+        {
+            "name": "process-data",
+            "node": "@blokjs/mapper",
+            "type": "module"
+        }
+    ],
+    "nodes": {
+        "fetch-data": {
+            "inputs": {
+                "url": "https://api.publicapis.org/entries",
+                "method": "GET",
+                "headers": {},
+                "var": "apiResponse"
+            }
+        },
+        "process-data": {
+            "inputs": {
+                "mapper": {
+                    "totalApis": "js/ctx.vars['fetch-data'].count",
+                    "categories": "js/ctx.vars['fetch-data'].categories"
+                }
+            }
+        }
+    }
+}
+```
+
+#### 🔹 How it Works:
+- The **API call node (`fetch-data`)** fetches API data and stores it in `ctx.vars['fetch-data']`.
+- The **mapper node (`process-data`)** extracts and processes values from `ctx.vars['fetch-data']`.
+
+---
+
+## 🎯 Key Takeaways
+
+- ✅ **`ctx` allows passing request data to nodes.**  
+- ✅ **Nodes modify and store values in `ctx.vars`.**  
+- ✅ **Nodes can dynamically read/write to `ctx.response.data`.**  
+- ✅ **`ctx.request.params`, `ctx.request.body`, and `ctx.response` drive workflow execution.**
+
+---
+
+## 🔍 Next Steps
+
+Now that you understand `ctx`, explore:
+- [Creating Custom Nodes](../CLI_Commands/Create_Node.md)
+- [Creating Workflows](../CLI_Commands/Create_Workflow.md)
+- [Examples](../examples.md)
+- [Index](../index.md)

package/dist/scaffold-repo/triggers/http/notes/examples.md

@@ -0,0 +1,104 @@
+# Blok Examples
+
+This examples provide a collection of workflows and bloks built with **Blok**, showcasing real-world use cases for building scalable, reusable, and modular backend services.
+
+## 🚀 Getting Started
+
+### Prerequisites
+- **Node.js** (Latest LTS version recommended)
+- **Docker & Docker Compose** (For running PostgreSQL instances)
+- **MongoDB** (For MongoDB-related examples)
+- **Blok CLI** (If available, install it globally)
+- **OpenAI API Key**: Required for workflows that utilize OpenAI services. Ensure you have a valid API key set in your environment variables.
+
+## 📌 Workflows
+
+The repository contains the following workflows:
+
+| Workflow | Description |
+|----------|-------------|
+| **countries-vs-facts.json** | Calls either a Countries API or a Cat Facts API |
+| **countries.json** | Retrieves country and city data from an API |
+| **dashboard-gen.json** | Generates insights and charts from PostgreSQL schema using OpenAI |
+| **db-manager.json** | SQL Query generator using OpenAI prompts with a web admin interface |
+| **films.json** | API to list films |
+| **launches-by-year.json** | Retrieves space launch data by year |
+| **mongodb.json** | REST API for MongoDB queries |
+| **workflow-docs.json** | Uses OpenAI to generate documentation for workflow JSON files |
+
+---
+
+## 🛠 Bloks
+
+These bloks are used within the workflows to handle specific tasks:
+
+| Blok | Description |
+|------------|-------------|
+| **mongodb-query.ts** | Executes queries on MongoDB |
+| **DirectoryManager.ts** | Retrieves the list of files in a directory |
+| **ErrorNode.ts** | Returns an error |
+| **FileManager.ts** | Reads the content of a file |
+| **OpenAI.ts** | Sends prompts to OpenAI |
+| **workflow-docs/ui/index.ts** | UI for workflow documentation (EJS, TailwindCSS, ReactJS) |
+| **postgres-query/index.ts** | Executes PostgreSQL queries |
+| **MapperNode.ts** | Performs data transformation |
+| **QueryGeneratorNode.ts** | Uses OpenAI to generate PostgreSQL queries from a prompt |
+| **db-manager/ui/index.ts** | Web admin interface for database queries (EJS, TailwindCSS, ReactJS) |
+| **ArrayMap.ts** | Transforms items within an array |
+| **DashboardChartGenerator.ts** | Uses OpenAI to generate charts using Chart.js |
+| **MemoryStorage.ts** | In-memory key-value store |
+| **MultipleQueryGeneratorNode.ts** | Uses OpenAI to generate PostgreSQL queries for dashboard charts |
+| **dashboard-generator/ui/index.ts** | Dashboard generator UI (EJS, TailwindCSS, ReactJS) |
+
+---
+
+## 🏗 Infrastructure
+
+This repository includes a **Docker Compose** setup to run a PostgreSQL database for testing workflows that require a database.
+
+### Start PostgreSQL Instance
+```sh
+cd infra
+docker-compose up -d
+```
+
+### Stop PostgreSQL Instance
+```sh
+cd infra
+docker-compose down
+```
+
+---
+
+### Required Environment Variables
+Before running the workflows, ensure you have the following environment variables set:
+```sh
+export OPENAI_API_KEY=your_openai_api_key
+export MONGODB_URI=your_mongodb_connection_string
+export MONGODB_DATABASE=your_database_name
+```
+
+---
+
+### Testing in Browser
+To test a workflow, open your browser and navigate to:
+```
+http://localhost:4000/{workflow-file-name}
+```
+Replace `{workflow-file-name}` with the actual file name of the workflow **without the extension**.
+
+For example, to test `countries.json`, navigate to:
+```
+http://localhost:4000/countries
+```
+
+---
+
+## 🔍 Next Steps
+
+Now that you understand the basics, dive deeper into `Blok` with the following resources:
+
+- [Context](./Core_Concepts/Context.md)
+- [Creating Workflows](./CLI_Commands/Create_Workflow.md)  
+- [Creating Custom Nodes](./CLI_Commands/Create_Node.md)
+- [Index](./index.md)

package/dist/scaffold-repo/triggers/http/notes/index.md

@@ -0,0 +1,51 @@
+# Quick Start Guide
+
+## 1. Setting Up Your Environment
+
+Get started with `Blok` by following these steps:
+
+### Prerequisites
+Ensure the following are installed:
+- **Node.js** (v22.14.0 LTS recommended)
+
+### Step 1: Create a New Project
+Run the command below to create a project:
+```sh
+npx blokctl@latest create project
+```
+Follow the prompts:
+1. Assign a project name.
+2. Select **HTTP trigger** (default).
+3. Choose **NodeJS** as the runtime (Python3 is in alpha).
+4. **Select Example Installation: YES** (recommended for discovery and learning).
+
+### Step 2: Navigate to Your Project and Start the Server
+```sh
+cd your-project-name
+pnpm run dev
+```
+Your server will be running at:  
+`http://localhost:4000`
+
+---
+
+## 2. Running the Example Workflows
+
+Explore the provided example workflows to get started. Access them via:
+
+- **Countries API**:  
+    `http://localhost:4000/countries`
+
+---
+
+## 🔍 Next Steps
+
+Now that you understand the basics, dive deeper into `Blok` with the following resources:
+
+- [Context](./Core_Concepts/Context.md)
+- [Creating Workflows](./CLI_Commands/Create_Workflow.md)  
+- [Creating Custom Nodes](./CLI_Commands/Create_Node.md)
+- [Examples](./examples.md)
+- [Authentication](./CLI_Commands/Authentication.md)
+- [Building](./CLI_Commands/Building.md)
+- [Deployment](./CLI_Commands/Deployment.md)