DEV Community: Frank Joseph

Mastra agent and Telex equals super integration

Frank Joseph — Tue, 04 Nov 2025 02:48:55 +0000

Building agent workflow has never been easy. However Mastra and Telex and are changing that narrative.

In this guide, I’ll walk you through how I integrated a Mastra AI Agent with Telex, using A2A (App-to-App) requests to enable smooth communication between the two platforms.

Telex is an educational platform similar to Slack, it supports apps and agents that interact using messages.
Mastra, on the other hand, is a modern framework for building, deploying, and scaling AI agents in production.

By combining the two, we can create a setup where Telex sends structured messages to Mastra, Mastra processes them intelligently using our agent, and then sends a meaningful response back, all through JSON-RPC.

Installing and Setting Up Mastra
Before writing any code, we’ll need to set up Mastra locally.
You can always check the official docs Mastra Getting Started

Step 1: Create and initialize your project

mkdir weather-agent
cd weather-agent
npm init -y

Step 2: Install Mastra

npm install @mastra/core @mastra/agents

Step 3: Define your Agent

Create a file src/mastra/agents/weather-agent.ts:

import { Agent } from '@mastra/core/agent';
import { Memory } from '@mastra/memory';
import { LibSQLStore } from '@mastra/libsql';
import { weatherTool } from '../tools/weather-tool.js';

export const weatherAgent = new Agent({
  name: 'Weather Agent',
  instructions: `
      You are a helpful weather assistant that provides accurate weather information and can help planning activities based on the weather

      Use the weatherTool to fetch current weather data.
`,
  model: 'google/gemini-2.5-pro',
  tools: { weatherTool },

  memory: new Memory({
    storage: new LibSQLStore({
      url: 'file:../mastra.db', // path is relative to the .mastra/output directory
    }),
  }),
});

Understanding the A2A Request Format

When Telex sends data to an AI agent, it follows a strict JSON-RPC 2.0 format.
Here’s what a sample Telex request looks like:

{
  "jsonrpc": "2.0",
  "id": "request-001",
  "method": "message/send",
  "params": {
    "message": {
      "kind": "message",
      "role": "user",
      "parts": [
        {
          "kind": "text",
          "text": "What's the weather condition"
        }
      ],
      "messageId": "msg-001"
    },
    "configuration": {
      "blocking": true
    }
  }
}

It is importatnt to make sure Mastra understands this format, extract the relevant message, and then send it to the agent for processing.

Setting Up the Custom A2A Endpoint

Mastra allows you to extend its API by registering custom routes.
We created one called /a2a/agent/:agentId to handle requests from Telex.

Here’s the full code for a2aRouter.ts:

import { registerApiRoute } from '@mastra/core/server';
import { randomUUID } from 'crypto';

interface A2AMessagePart {
  kind: 'text' | 'data';
  text?: string;
  data?: any;
}

interface A2AMessage {
  role: string;
  parts: A2AMessagePart[];
  messageId?: string;
  taskId?: string;
}

export const a2aAgentRoute = registerApiRoute('/a2a/agent/:agentId', {
  method: 'POST',
  handler: async (c: any) => {
    try {
      const mastra = c.get('mastra');
      const agentId = c.req.param('agentId');

      // Parse JSON-RPC 2.0 request
      const body = await c.req.json();
      const { jsonrpc, id: requestId, method, params } = body;

      // Validate JSON-RPC 2.0 format
      if (jsonrpc !== '2.0' || !requestId) {
        return c.json(
          {
            jsonrpc: '2.0',
            id: requestId || null,
            error: {
              code: -32600,
              message: 'Invalid Request: jsonrpc must be "2.0" and id is required'
            }
          },
          400
        );
      }

      const agent = mastra.getAgent(agentId);
      if (!agent) {
        return c.json(
          {
            jsonrpc: '2.0',
            id: requestId,
            error: {
              code: -32602,
              message: `Agent '${agentId}' not found`
            }
          },
          404
        );
      }

      // Extract messages
      const { message, messages, contextId, taskId, metadata } = params || {};

      const messagesList: A2AMessage[] = message
        ? [message]
        : Array.isArray(messages)
        ? messages
        : [];

      // Convert A2A messages to Mastra format
      const mastraMessages = messagesList.map((msg) => ({
        role: msg.role,
        content:
          msg.parts
            ?.map((part) => {
              if (part.kind === 'text') return part.text || '';
              if (part.kind === 'data') return JSON.stringify(part.data || {});
              return '';
            })
            .join('\n') || ''
      }));

      // Execute agent
      const response = await agent.generate(mastraMessages);
      const agentText = response.text || '';

      // Build artifacts
      const artifacts = [
        {
          artifactId: randomUUID(),
          name: `${agentId}Response`,
          parts: [{ kind: 'text', text: agentText }]
        }
      ];

      if (response.toolResults?.length) {
        artifacts.push({
          artifactId: randomUUID(),
          name: 'ToolResults',
          parts: response.toolResults.map((result: any) => ({
            kind: 'data',
            data: result
          }))
        });
      }

      // Build conversation history
      const history = [
        ...messagesList.map((msg) => ({
          kind: 'message',
          role: msg.role,
          parts: msg.parts,
          messageId: msg.messageId || randomUUID(),
          taskId: msg.taskId || taskId || randomUUID()
        })),
        {
          kind: 'message',
          role: 'agent',
          parts: [{ kind: 'text', text: agentText }],
          messageId: randomUUID(),
          taskId: taskId || randomUUID()
        }
      ];

      // Return A2A-compliant response
      return c.json({
        jsonrpc: '2.0',
        id: requestId,
        result: {
          id: taskId || randomUUID(),
          contextId: contextId || randomUUID(),
          status: {
            state: 'completed',
            timestamp: new Date().toISOString(),
            message: {
              messageId: randomUUID(),
              role: 'agent',
              parts: [{ kind: 'text', text: agentText }],
              kind: 'message'
            }
          },
          artifacts,
          history,
          kind: 'task'
        }
      });
    } catch (error: any) {
      return c.json(
        {
          jsonrpc: '2.0',
          id: null,
          error: {
            code: -32603,
            message: 'Internal error',
            data: { details: error?.message || String(error) }
          }
        },
        500
      );
    }
  }
});

Linking the Route to Mastra

In the mastra/index.ts, register the new route like this:


import { Mastra } from '@mastra/core/mastra';
import { PinoLogger } from '@mastra/loggers';
import { LibSQLStore } from '@mastra/libsql';
import { weatherWorkflow } from './workflows/weather-workflow.js';
import { weatherAgent } from './agents/weather-agent.js';
import { a2aAgentRoute } from '../mastra/routes/a2a-agent-route.js';


export const mastra = new Mastra({
  workflows: { weatherWorkflow },
  agents: { weatherAgent },
  storage: new LibSQLStore({
    // stores observability, scores, ... into memory storage, if it needs to persist, change to file:../mastra.db
    url: ":memory:",
  }),
  logger: new PinoLogger({
    name: 'Mastra',
    level: 'info',
  }),
  telemetry: {
    // Telemetry is deprecated and will be removed in the Nov 4th release
    enabled: false, 
  },
  observability: {
    // Enables DefaultExporter and CloudExporter for AI tracing
    default: { enabled: true }, 
  },

   server: {
    build: {
      openAPIDocs: true,
      swaggerUI: true,
    },
    apiRoutes: [
      a2aAgentRoute
    ]
  }
});

Deployment to Mastra Cloud
Once you’ve created your project and agent locally, simply push:

npx mastra deploy
After deployment, you’ll get a public URL like:

https://white-cloud-noon.mastra.cloud/a2a/agent/weatherAgent
This is the endpoint you’ll register on Telex under your A2A app configuration.

Now, Telex will send messages directly to your agent and receive responses in real time.

HNG13 Stage 0 Task

Frank Joseph — Fri, 17 Oct 2025 00:23:08 +0000

Update: I joined the HNG13 internship by Hotels.ng.

Here is a break down of the stage 0 task and what I learned doing this task.
The task required me to build a RESTful API endpoint that returns my profile information along with a dynamic cat fact fetched from an external API.

{ "status": "success", "user": { "email": "<your email>", "name": "<your full name>", "stack": "<your backend stack>" }, "timestamp": "<current UTC time in ISO 8601 format>", "fact": "<random cat fact from Cat Facts API>" }

The response must be in the JSON format above.
The fact is fetched from this source: catfact.

Here are the project specification:

Field specifications:

status — Must always be the string "success"
user.email — Your personal email address
user.name — Your full name
user.stack — Your backend technology stack (e.g., "Node.js/Express", "Python/Django", "Go/Gin"). I used Node.js/Express for my project
timestamp — Current UTC time in ISO 8601 format (e.g., "2025-10-15T12:34:56.789Z")
fact — A random cat fact fetched from the Cat Facts API

It's simple project, However, I learned a few things working on this project.

I learned to use express-rate-limit package
Hosted my API on railway.com. I encountered a few challenges using railway as it was my time.
Split my project into server.js and app.js. (Application server logic lives inside the server.js file while the main application logic, middlewares, cors, and rate limiting logic lives inside the app.js file)

With this project, I learned to fetch resources from external APIs and handle errors gracefully when the API fails.

Visit this github repository to see the full code and README file. Code

Building a PDF-to-Markdown Converter Using Cardinal API

Frank Joseph — Thu, 16 Oct 2025 23:53:20 +0000

Document processing involves the processes or methods and technologies used to capture, digitize, extract, and transform information from both physical and digital documents into structured, machine-readable data.

Document processing is an everyday activity for startups. Depending on the workflow and the volume of the document, processing documents could be tedious and time-consuming tasks. To successfully convert a document from one form to another while preserving its structure requires thoughtful planning and the right document-processing solution. In this article, we'll explore a state of the art AI powered document processing software; Cardinal API, look at some of the processing tasks that can be performed with Cardinal API and show a demo solution using the Cardinal API to build a PDF to Markdown converter.

What is Cardinal API?

According to Y Combinator Cardinal is the most accurate document processing API for Healthcare.

Cardinal API in simple terms gives team the ability to transform any document into structured data. At the time of writing this, here are the list of accepted files types Cardinal API currently process:

.pdf
.jpeg/jpg
.png

💡 While Cardinal does not natively support Excel (.xls / .xlsx) or CSV (.csv) files, you can convert them to PDF on your own and process them through Cardinal.

The following formats are not yet supported but are planned for future releases:

.doc / .docx — Microsoft Word
.tiff — Tagged Image File Format
.odt / .ott — OpenDocument Text & Template
.rtf — Rich Text Format
.txt — Plain Text
.html / .htm — HTML Document
.xml — XML Document
.wps — Microsoft Works Word Processor
.wpd — WordPerfect Document
.ods / .ots — OpenDocument Spreadsheet & Template
.ppt / .pptx — Microsoft PowerPoint
.odp / .otp — OpenDocument Presentation & Template

Use cases for Cardinal API

Here are some use cases for Cardinal API:

How to build A PDF to Markdown Converter using Cardinal API

To use the Cardinal API, you must:

Create an account
Have an API key

To do the above, visit this link
Login with your Gmail or with your company email

After you are one with the steps above, you'll be rerouted to your Cardinal dashboard

At this point, you can request a free Cardinal API key. The free API key gives you access to 50 free requests. That's a lot to get started.
To request a free API key, type your preferred API key name in the text area as shown in your dashboard above and click on the Add Key button.

However, if you want to take things a step further you can subscribe to

Building a PDF-to-Markdown Converter Using Cardinal API

Frank Joseph — Tue, 30 Sep 2025 16:07:10 +0000

What is Cardinal API?

According to Y Combinator Cardinal is the most accurate document processing API for Healthcare.

.pdf
.jpeg/jpg
.png

💡 While Cardinal does not natively support Excel (.xls / .xlsx) or CSV (.csv) files, you can convert them to PDF on your own and process them through Cardinal.

The following formats are not yet supported but are planned for future releases:

.doc / .docx — Microsoft Word
.tiff — Tagged Image File Format
.odt / .ott — OpenDocument Text & Template
.rtf — Rich Text Format
.txt — Plain Text
.html / .htm — HTML Document
.xml — XML Document
.wps — Microsoft Works Word Processor
.wpd — WordPerfect Document
.ods / .ots — OpenDocument Spreadsheet & Template
.ppt / .pptx — Microsoft PowerPoint
.odp / .otp — OpenDocument Presentation & Template

Use cases for Cardinal API

Here are some use cases for Cardinal API:

How to build A PDF to Markdown Converter using Cardinal API

To use the Cardinal API, you must:

Create an account
Have an API key

To do the above, visit this link
Login with your Gmail or with your company email

After you done are one with the steps above, you'll be rerouted to your Cardinal dashboard

However, if you want to take things a step further you can subscribe to a plan. Click here to see the pricing.

Now that we cleared all the prerequisites, let's build our PDF to Markdown Converter. Here is a live version of our application

Step 1: Create a HTML file and write the following markup in it.

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>Cardinal API - Secure PDF/Image to Markdown Converter</title>
    <link rel="stylesheet" href="style.css">
</head>
<body>
 <div class="container">
        <div class="header">
            <h1>🔐 Secure Cardinal API Converter</h1>
            <p>Convert PDFs and images to clean Markdown with secure API key handling</p>
        </div>

        <!-- Security Notice -->
        <div class="security-notice">
            <h4>🛡️ Security First</h4>
            <p>Your API key is stored securely in your browser and never transmitted to any third parties. It's only sent directly to Cardinal's API for conversions.</p>
        </div>

        <!-- API Key Setup -->
        <div class="api-key-setup">
            <h2 style="margin-bottom: 15px;">🔑 API Key Configuration</h2>
            <p style="color: #666; margin-bottom: 15px;">
                Enter your Cardinal API key to get started. You can get one from 
                <a href="https://dashboard.trycardinal.ai" target="_blank" style="color: #667eea;">Cardinal Dashboard</a>.
            </p>

            <div class="api-key-input">
                <input 
                    type="password" 
                    id="apiKeyInput" 
                    class="api-key-field" 
                    placeholder="Enter your Cardinal API key..."
                    autocomplete="off"
                >
                <button type="button" class="api-key-toggle" id="toggleApiKey">Show</button>
                <button type="button" class="api-key-save" id="saveApiKey">Validate & Save</button>
            </div>

            <div style="display: flex; align-items: center; gap: 10px; margin-top: 10px;">
                <input type="checkbox" id="rememberApiKey">
                <label for="rememberApiKey" style="font-size: 0.9rem; color: #666;">
                    Remember API key (stored locally in your browser)
                </label>
            </div>

            <div id="apiStatus" class="api-status" style="display: none;"></div>

            <div style="margin-top: 15px; font-size: 0.8rem; color: #888;">
                <p>💡 <strong>Tips:</strong></p>
                <ul style="margin-left: 20px; margin-top: 5px;">
                    <li>API key is encrypted and stored only in your browser</li>
                    <li>You can clear stored keys anytime using the "Clear Keys" button</li>
                    <li>Keys are automatically validated before use</li>
                </ul>
            </div>

            <div style="margin-top: 15px;">
                <button type="button" id="clearApiKeys" style="background: #dc3545; color: white; border: none; padding: 8px 16px; border-radius: 4px; cursor: pointer; font-size: 0.9rem;">
                    🗑️ Clear Stored Keys
                </button>
            </div>
        </div>

        <!-- Main Content (Initially Disabled) -->
        <div id="mainContent" class="content-disabled">
            <!-- Options Section -->
            <div class="options-section">
                <h2 class="section-title">⚙️ Conversion Options</h2>
                <div class="options-grid">
                    <div class="option-item">
                        <input type="checkbox" id="markdown" checked>
                        <label for="markdown">Enable Markdown output</label>
                    </div>
                    <div class="option-item">
                        <input type="checkbox" id="denseTables" checked>
                        <label for="denseTables">Dense table formatting</label>
                    </div>
                    <div class="option-item">
                        <input type="checkbox" id="preserveLayout" checked>
                        <label for="preserveLayout">Preserve original layout</label>
                    </div>
                    <div class="option-item">
                        <input type="checkbox" id="cleanText" checked>
                        <label for="cleanText">Clean text output</label>
                    </div>
                </div>
            </div>

            <div class="main-content">
                <!-- File Upload Section -->
                <div class="upload-section">
                    <h2 class="section-title">📁 Upload Files</h2>
                    <div id="upload-container"></div>
                </div>

                <!-- URL Conversion Section -->
                <div class="url-section">
                    <h2 class="section-title">🔗 Convert from URL</h2>
                    <div class="url-input-group">
                        <input type="url" id="fileUrl" placeholder="https://example.com/document.pdf" class="url-input">
                        <button id="convertUrl" class="convert-btn">Convert</button>
                    </div>
                    <p style="color: #666; font-size: 0.9rem;">
                        Enter the URL of a PDF or image file to convert it to Markdown
                    </p>
                    <div id="url-results"></div>
                </div>
            </div>
        </div>

        <!-- Results Container -->
        <div id="results-container"></div>
    </div>
   <script src="index.js"></script>
 </body>
</html>

Step 2: Create a CSS (style.css) file and write the following styles in it:

 {
            margin: 0;
            padding: 0;
            box-sizing: border-box;
        }

        body {
            font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
            line-height: 1.6;
            color: #333;
            background-color: #f8f9fa;
        }

        .container {
            max-width: 1200px;
            margin: 0 auto;
            padding: 20px;
        }

        .header {
            text-align: center;
            margin-bottom: 40px;
            padding: 40px 20px;
            background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
            border-radius: 12px;
            color: white;
        }

        .api-key-setup {
            background: white;
            padding: 30px;
            border-radius: 12px;
            box-shadow: 0 4px 20px rgba(0,0,0,0.1);
            margin-bottom: 30px;
            border-left: 4px solid #667eea;
        }

        .api-key-input {
            display: flex;
            gap: 10px;
            margin: 15px 0;
            align-items: center;
        }

        .api-key-field {
            flex: 1;
            padding: 12px;
            border: 1px solid #ddd;
            border-radius: 6px;
            font-family: 'Courier New', monospace;
            font-size: 0.9rem;
        }

        .api-key-toggle {
            background: #6c757d;
            color: white;
            border: none;
            padding: 12px 16px;
            border-radius: 6px;
            cursor: pointer;
            min-width: 80px;
        }

        .api-key-save {
            background: #28a745;
            color: white;
            border: none;
            padding: 12px 20px;
            border-radius: 6px;
            cursor: pointer;
            font-weight: 500;
        }

        .api-key-save:disabled {
            background: #ccc;
            cursor: not-allowed;
        }

        .api-status {
            margin-top: 15px;
            padding: 10px;
            border-radius: 6px;
            font-size: 0.9rem;
        }

        .status-success {
            background: #d4edda;
            color: #155724;
            border: 1px solid #c3e6cb;
        }

        .status-error {
            background: #f8d7da;
            color: #721c24;
            border: 1px solid #f5c6cb;
        }

        .status-info {
            background: #d1ecf1;
            color: #0c5460;
            border: 1px solid #bee5eb;
        }

        .main-content {
            display: grid;
            grid-template-columns: 1fr 1fr;
            gap: 40px;
            margin-bottom: 40px;
        }

        .content-disabled {
            opacity: 0.5;
            pointer-events: none;
        }

        .upload-section, .url-section {
            background: white;
            padding: 30px;
            border-radius: 12px;
            box-shadow: 0 4px 20px rgba(0,0,0,0.1);
        }

        .section-title {
            font-size: 1.4rem;
            margin-bottom: 20px;
            color: #2c3e50;
            border-bottom: 2px solid #e9ecef;
            padding-bottom: 10px;
        }

        .drop-zone {
            border: 2px dashed #ddd;
            border-radius: 12px;
            padding: 40px 20px;
            text-align: center;
            cursor: pointer;
            transition: all 0.3s ease;
            background: #fafbfc;
        }

        .drop-zone:hover, .drop-zone.drag-over {
            border-color: #667eea;
            background-color: #f0f3ff;
            transform: translateY(-2px);
        }

        .browse-btn {
            background: #667eea;
            color: white;
            border: none;
            padding: 10px 20px;
            border-radius: 6px;
            cursor: pointer;
            font-size: 1rem;
        }

        .url-input-group {
            display: flex;
            gap: 10px;
            margin-bottom: 20px;
        }

        .url-input {
            flex: 1;
            padding: 12px;
            border: 1px solid #ddd;
            border-radius: 6px;
            font-size: 1rem;
        }

        .convert-btn {
            background: #48bb78;
            color: white;
            border: none;
            padding: 12px 24px;
            border-radius: 6px;
            cursor: pointer;
            font-size: 1rem;
        }

        .options-section {
            background: white;
            padding: 30px;
            border-radius: 12px;
            box-shadow: 0 4px 20px rgba(0,0,0,0.1);
            margin-bottom: 40px;
        }

        .options-grid {
            display: grid;
            grid-template-columns: repeat(auto-fit, minmax(200px, 1fr));
            gap: 20px;
        }

        .option-item {
            display: flex;
            align-items: center;
            gap: 10px;
        }

        .conversion-progress {
            margin-top: 20px;
            padding: 20px;
            border-radius: 8px;
            background: white;
            border-left: 4px solid #667eea;
            box-shadow: 0 2px 10px rgba(0,0,0,0.1);
        }

        .progress-bar {
            width: 100%;
            height: 8px;
            background: #e9ecef;
            border-radius: 4px;
            overflow: hidden;
            margin: 15px 0;
        }

        .progress-bar-fill {
            height: 100%;
            background: linear-gradient(90deg, #48bb78, #38a169);
            width: 0%;
            transition: width 0.3s ease;
        }

        .security-notice {
            background: #fff3cd;
            border: 1px solid #ffeaa7;
            border-radius: 6px;
            padding: 15px;
            margin-bottom: 20px;
        }

        .security-notice h4 {
            color: #856404;
            margin-bottom: 5px;
        }

        .security-notice p {
            color: #856404;
            font-size: 0.9rem;
            margin: 0;
        }

        @media (max-width: 768px) {
            .main-content {
                grid-template-columns: 1fr;
            }

            .api-key-input {
                flex-direction: column;
                align-items: stretch;
            }
        }

Step 3: Create a JavaScript (index.js) file and write the following code in it:

// Secure Cardinal API Converter Class
        class SecureCardinalConverter {
            constructor() {
                this.apiKey = null;
                this.baseUrl = 'https://api.trycardinal.ai';
                this.isValidated = false;
            }

            setApiKey(apiKey) {
                if (!apiKey || apiKey.trim() === '') {
                    throw new Error('API key is required');
                }
                this.apiKey = apiKey.trim();
                this.isValidated = false;
            }

            async validateApiKey() {
                if (!this.apiKey) {
                    throw new Error('API key not set');
                }

                try {
                    // Test with a lightweight request
                    const response = await fetch(`${this.baseUrl}/markdown`, {
                        method: 'POST',
                        headers: { 
                            'x-api-key': this.apiKey,
                            'Content-Type': 'application/json'
                        },
                        body: JSON.stringify({
                            fileUrl: 'https://httpbin.org/status/404', // This will fail but validates auth
                            markdown: true
                        })
                    });

                    // API key is valid if we don't get 401/403
                    this.isValidated = ![401, 403].includes(response.status);
                    return this.isValidated;
                } catch (error) {
                    console.warn('API validation error:', error);
                    return false;
                }
            }

            async convertFile(file, options = {}) {
                if (!this.apiKey || !this.isValidated) {
                    throw new Error('Please validate your API key first');
                }

                const formData = new FormData();
                formData.append('file', file);

                Object.keys(options).forEach(key => {
                    formData.append(key, options[key].toString());
                });

                const response = await fetch(`${this.baseUrl}/markdown`, {
                    method: 'POST',
                    headers: { 'x-api-key': this.apiKey },
                    body: formData
                });

                if (!response.ok) {
                    if (response.status === 401 || response.status === 403) {
                        this.isValidated = false;
                        throw new Error('API key is invalid or expired. Please check your key.');
                    }
                    throw new Error(`API request failed: ${response.status} ${response.statusText}`);
                }

                const result = await response.json();
                return result.pages?.[0]?.content || result.content || '';
            }

            async convertUrl(url, options = {}) {
                if (!this.apiKey || !this.isValidated) {
                    throw new Error('Please validate your API key first');
                }

                const response = await fetch(`${this.baseUrl}/markdown`, {
                    method: 'POST',
                    headers: {
                        'x-api-key': this.apiKey,
                        'Content-Type': 'application/json'
                    },
                    body: JSON.stringify({ fileUrl: url, ...options })
                });

                if (!response.ok) {
                    if (response.status === 401 || response.status === 403) {
                        this.isValidated = false;
                        throw new Error('API key is invalid or expired. Please check your key.');
                    }
                    throw new Error(`API request failed: ${response.status} ${response.statusText}`);
                }

                const result = await response.json();
                return result.pages?.[0]?.content || result.content || '';
            }

            validateFile(file) {
                const maxSize = 10 * 1024 * 1024;
                const allowedTypes = [
                    'application/pdf', 'image/jpeg', 'image/jpg', 
                    'image/png', 'image/gif', 'image/bmp', 'image/tiff'
                ];

                if (file.size > maxSize) {
                    throw new Error('File size exceeds 10MB limit');
                }

                if (!allowedTypes.includes(file.type)) {
                    throw new Error('Unsupported file type. Please use PDF or image files.');
                }
            }
        }

        // Secure Storage Utilities
        const SecureStorage = {
            // Simple encryption for local storage (basic obfuscation)
            encrypt(text) {
                return btoa(encodeURIComponent(text));
            },

            decrypt(encoded) {
                try {
                    return decodeURIComponent(atob(encoded));
                } catch {
                    return null;
                }
            },

            store(key, value, remember = false) {
                const storage = remember ? localStorage : sessionStorage;
                storage.setItem(key, this.encrypt(value));
            },

            retrieve(key) {
                // Check session storage first, then local storage
                let value = sessionStorage.getItem(key) || localStorage.getItem(key);
                return value ? this.decrypt(value) : null;
            },

            clear(key) {
                sessionStorage.removeItem(key);
                localStorage.removeItem(key);
            }
        };

        // Initialize Application
        document.addEventListener('DOMContentLoaded', function() {
            const converter = new SecureCardinalConverter();

            // DOM Elements
            const apiKeyInput = document.getElementById('apiKeyInput');
            const toggleApiKey = document.getElementById('toggleApiKey');
            const saveApiKey = document.getElementById('saveApiKey');
            const rememberApiKey = document.getElementById('rememberApiKey');
            const apiStatus = document.getElementById('apiStatus');
            const clearApiKeys = document.getElementById('clearApiKeys');
            const mainContent = document.getElementById('mainContent');

            // Load stored API key
            const storedApiKey = SecureStorage.retrieve('cardinal_api_key');
            if (storedApiKey) {
                apiKeyInput.value = storedApiKey;
                rememberApiKey.checked = localStorage.getItem('cardinal_api_key') !== null;
                validateApiKey(storedApiKey, false);
            }

            // Toggle API key visibility
            toggleApiKey.addEventListener('click', function() {
                const isPassword = apiKeyInput.type === 'password';
                apiKeyInput.type = isPassword ? 'text' : 'password';
                toggleApiKey.textContent = isPassword ? 'Hide' : 'Show';
            });

            // Save and validate API key
            saveApiKey.addEventListener('click', function() {
                const apiKey = apiKeyInput.value.trim();
                if (!apiKey) {
                    showStatus('Please enter an API key', 'error');
                    return;
                }
                validateApiKey(apiKey, true);
            });

            // Clear stored keys
            clearApiKeys.addEventListener('click', function() {
                if (confirm('Are you sure you want to clear all stored API keys?')) {
                    SecureStorage.clear('cardinal_api_key');
                    apiKeyInput.value = '';
                    rememberApiKey.checked = false;
                    showStatus('All stored API keys have been cleared', 'info');
                    mainContent.classList.add('content-disabled');
                }
            });

            // Enter key support
            apiKeyInput.addEventListener('keypress', function(e) {
                if (e.key === 'Enter') {
                    saveApiKey.click();
                }
            });

            async function validateApiKey(apiKey, showFeedback = true) {
                if (showFeedback) {
                    saveApiKey.disabled = true;
                    saveApiKey.textContent = 'Validating...';
                    showStatus('Validating API key...', 'info');
                }

                try {
                    converter.setApiKey(apiKey);
                    const isValid = await converter.validateApiKey();

                    if (isValid) {
                        // Store the API key
                        SecureStorage.store('cardinal_api_key', apiKey, rememberApiKey.checked);

                        if (showFeedback) {
                            showStatus('✅ API key validated successfully!', 'success');
                        }

                        // Enable main content
                        mainContent.classList.remove('content-disabled');

                        // Initialize the converter interface
                        initializeConverterInterface();
                    } else {
                        throw new Error('Invalid API key or service unavailable');
                    }
                } catch (error) {
                    if (showFeedback) {
                        showStatus(`❌ ${error.message}`, 'error');
                    }
                    mainContent.classList.add('content-disabled');
                } finally {
                    if (showFeedback) {
                        saveApiKey.disabled = false;
                        saveApiKey.textContent = 'Validate & Save';
                    }
                }
            }

            function showStatus(message, type) {
                apiStatus.textContent = message;
                apiStatus.className = `api-status status-${type}`;
                apiStatus.style.display = 'block';

                if (type === 'success' || type === 'info') {
                    setTimeout(() => {
                        apiStatus.style.display = 'none';
                    }, 5000);
                }
            }

            function initializeConverterInterface() {
                // Initialize file upload interface
                createDropZone();
                setupUrlConversion();
            }

            // Rest of the converter interface code (same as before but using the secure converter)
            function getConversionOptions() {
                return {
                    markdown: document.getElementById('markdown').checked,
                    denseTables: document.getElementById('denseTables').checked,
                    preserveLayout: document.getElementById('preserveLayout').checked,
                    cleanText: document.getElementById('cleanText').checked
                };
            }

            function createDropZone() {
                const container = document.getElementById('upload-container');
                container.innerHTML = ''; // Clear any existing content

                const fileInput = document.createElement('input');
                fileInput.type = 'file';
                fileInput.accept = '.pdf,image/*';
                fileInput.multiple = true;
                fileInput.style.display = 'none';

                const dropZone = document.createElement('div');
                dropZone.className = 'drop-zone';
                dropZone.innerHTML = `
                    <div class="drop-zone-content">
                        <p>📄 Drop PDF or image files here or <button type="button" class="browse-btn">browse</button></p>
                        <small>Supported formats: PDF, JPEG, PNG, GIF, BMP, TIFF (max 10MB each)</small>
                    </div>
                `;

                container.appendChild(dropZone);
                container.appendChild(fileInput);

                // Event listeners
                dropZone.addEventListener('click', () => fileInput.click());
                dropZone.querySelector('.browse-btn').addEventListener('click', (e) => {
                    e.stopPropagation();
                    fileInput.click();
                });

                // Drag and drop events
                ['dragenter', 'dragover', 'dragleave', 'drop'].forEach(eventName => {
                    dropZone.addEventListener(eventName, preventDefaults);
                });

                function preventDefaults(e) {
                    e.preventDefault();
                    e.stopPropagation();
                }

                ['dragenter', 'dragover'].forEach(eventName => {
                    dropZone.addEventListener(eventName, () => dropZone.classList.add('drag-over'));
                });

                ['dragleave', 'drop'].forEach(eventName => {
                    dropZone.addEventListener(eventName, () => dropZone.classList.remove('drag-over'));
                });

                dropZone.addEventListener('drop', (e) => handleFiles(e.dataTransfer.files));
                fileInput.addEventListener('change', (e) => handleFiles(e.target.files));
            }

            async function handleFiles(files) {
                const fileList = Array.from(files);

                for (const file of fileList) {
                    try {
                        converter.validateFile(file);
                        await processFile(file);
                    } catch (error) {
                        showError(`Error with file "${file.name}": ${error.message}`);
                    }
                }
            }

            async function processFile(file) {
                const resultsContainer = document.getElementById('upload-container');

                const progressDiv = document.createElement('div');
                progressDiv.className = 'conversion-progress';
                progressDiv.innerHTML = `
                    <div style="display: flex; justify-content: space-between; align-items: center;">
                        <strong>🔄 Converting: ${file.name}</strong>
                        <span class="file-size">${formatFileSize(file.size)}</span>
                    </div>
                    <div class="progress-bar">
                        <div class="progress-bar-fill"></div>
                    </div>
                    <div class="status">Initializing conversion...</div>
                `;
                resultsContainer.appendChild(progressDiv);

                const progressBar = progressDiv.querySelector('.progress-bar-fill');
                const statusText = progressDiv.querySelector('.status');

                try {
                    updateProgress(progressBar, statusText, 25, 'Uploading file...');

                    const options = getConversionOptions();
                    const markdown = await converter.convertFile(file, options);

                    updateProgress(progressBar, statusText, 100, 'Conversion completed!');

                    setTimeout(() => {
                        displayResult(file.name, markdown, progressDiv);
                    }, 500);

                } catch (error) {
                    progressDiv.innerHTML = `
                        <div style="background: #f8d7da; color: #721c24; padding: 15px; border-radius: 8px; border-left: 4px solid #dc3545;">
                            <strong>❌ Error converting ${file.name}</strong>
                            <p>${error.message}</p>
                            ${error.message.includes('API key') ? '<p><em>Please check your API key configuration above.</em></p>' : ''}
                        </div>
                    `;
                }
            }

            function setupUrlConversion() {
                const urlInput = document.getElementById('fileUrl');
                const convertBtn = document.getElementById('convertUrl');
                const resultsDiv = document.getElementById('url-results');

                convertBtn.addEventListener('click', async () => {
                    const url = urlInput.value.trim();

                    if (!url) {
                        showError('Please enter a valid URL');
                        return;
                    }

                    if (!isValidUrl(url)) {
                        showError('Please enter a valid URL starting with http:// or https://');
                        return;
                    }

                    convertBtn.disabled = true;
                    convertBtn.textContent = 'Converting...';
                    resultsDiv.innerHTML = '';

                    const progressDiv = document.createElement('div');
                    progressDiv.className = 'conversion-progress';
                    progressDiv.innerHTML = `
                        <div><strong>🔄 Converting URL: ${url}</strong></div>
                        <div class="progress-bar">
                            <div class="progress-bar-fill" style="width: 50%"></div>
                        </div>
                        <div class="status">Processing URL...</div>
                    `;
                    resultsDiv.appendChild(progressDiv);

                    try {
                        const options = getConversionOptions();
                        const markdown = await converter.convertUrl(url, options);

                        const fileName = url.split('/').pop() || 'converted-document';
                        displayResult(fileName, markdown, progressDiv);

                    } catch (error) {
                        progressDiv.innerHTML = `
                            <div style="background: #f8d7da; color: #721c24; padding: 15px; border-radius: 8px; border-left: 4px solid #dc3545;">
                                <strong>❌ Error converting URL</strong>
                                <p>${error.message}</p>
                                ${error.message.includes('API key') ? '<p><em>Please check your API key configuration above.</em></p>' : ''}
                            </div>
                        `;
                    } finally {
                        convertBtn.disabled = false;
                        convertBtn.textContent = 'Convert';
                    }
                });

                urlInput.addEventListener('keypress', (e) => {
                    if (e.key === 'Enter') {
                        convertBtn.click();
                    }
                });
            }

            function updateProgress(progressBar, statusText, progress, status) {
                progressBar.style.width = `${progress}%`;
                statusText.textContent = status;
            }

            function displayResult(fileName, markdown, container) {
                container.innerHTML = `
                    <div style="margin-bottom: 15px;">
                        <strong>✅ ${fileName} - Conversion completed!</strong>
                        <span style="color: #666; font-size: 0.9rem;">(${formatFileSize(markdown.length)} of markdown)</span>
                    </div>
                    <div style="display: flex; gap: 10px; margin-bottom: 15px; flex-wrap: wrap;">
                        <button class="copy-btn" style="background: #4299e1; color: white; border: none; padding: 8px 16px; border-radius: 4px; cursor: pointer;">📋 Copy to Clipboard</button>
                        <button class="download-btn" style="background: #48bb78; color: white; border: none; padding: 8px 16px; border-radius: 4px; cursor: pointer;">💾 Download Markdown</button>
                        <button class="view-btn" style="background: #ed8936; color: white; border: none; padding: 8px 16px; border-radius: 4px; cursor: pointer;">👁️ View Content</button>
                    </div>
                    <div class="markdown-preview" style="display: none; background: #f8f9fa; padding: 20px; border-radius: 8px; max-height: 400px; overflow-y: auto; font-family: 'Courier New', monospace; font-size: 0.9rem; white-space: pre-wrap; border: 1px solid #e9ecef;">
                        <div style="margin-bottom: 10px; font-weight: bold; font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;">Markdown Content:</div>${escapeHtml(markdown)}
                    </div>
                `;

                const copyBtn = container.querySelector('.copy-btn');
                const downloadBtn = container.querySelector('.download-btn');
                const viewBtn = container.querySelector('.view-btn');
                const previewDiv = container.querySelector('.markdown-preview');

                copyBtn.addEventListener('click', async () => {
                    try {
                        await navigator.clipboard.writeText(markdown);
                        copyBtn.innerHTML = '✅ Copied!';
                        setTimeout(() => copyBtn.innerHTML = '📋 Copy to Clipboard', 2000);
                    } catch (err) {
                        showError('Failed to copy to clipboard');
                    }
                });

                downloadBtn.addEventListener('click', () => {
                    downloadMarkdown(markdown, fileName);
                });

                viewBtn.addEventListener('click', () => {
                    const isVisible = previewDiv.style.display !== 'none';
                    previewDiv.style.display = isVisible ? 'none' : 'block';
                    viewBtn.innerHTML = isVisible ? '👁️ View Content' : '🙈 Hide Content';
                });
            }

            function formatFileSize(bytes) {
                if (bytes === 0) return '0 Bytes';
                const k = 1024;
                const sizes = ['Bytes', 'KB', 'MB', 'GB'];
                const i = Math.floor(Math.log(bytes) / Math.log(k));
                return parseFloat((bytes / Math.pow(k, i)).toFixed(2)) + ' ' + sizes[i];
            }

            function escapeHtml(text) {
                const div = document.createElement('div');
                div.textContent = text;
                return div.innerHTML;
            }

            function isValidUrl(string) {
                try {
                    const url = new URL(string);
                    return url.protocol === 'http:' || url.protocol === 'https:';
                } catch (_) {
                    return false;
                }
            }

            function downloadMarkdown(content, originalFileName) {
                const blob = new Blob([content], { type: 'text/markdown;charset=utf-8' });
                const url = URL.createObjectURL(blob);
                const a = document.createElement('a');
                a.href = url;
                a.download = `${originalFileName.replace(/\.[^/.]+$/, '')}.md`;
                document.body.appendChild(a);
                a.click();
                document.body.removeChild(a);
                URL.revokeObjectURL(url);
            }

            function showError(message) {
                const errorDiv = document.createElement('div');
                errorDiv.style.cssText = `
                    background: #f8d7da; 
                    color: #721c24; 
                    padding: 15px; 
                    border-radius: 8px; 
                    margin-top: 15px; 
                    border-left: 4px solid #dc3545;
                `;
                errorDiv.innerHTML = `<strong>❌ Error:</strong> ${message}`;

                const container = document.getElementById('results-container');
                container.appendChild(errorDiv);

                setTimeout(() => {
                    if (errorDiv.parentNode) {
                        errorDiv.parentNode.removeChild(errorDiv);
                    }
                }, 5000);
            }
        });

At this point, we have a fully functional web application you can view on your browser. You should see something like this:

To use this web app,

Copy and paste your API key in the API Key Configuration text area, - - Click the Validate and Save button
Go to the Upload file and upload the file you want to convert to Markdown or use the URL conversion option.

How to use the Python better_profanity Filter API with GraphQL

Frank Joseph — Tue, 12 Nov 2024 10:14:32 +0000

As social interaction on the web continues to grow especially as generative AIs continue to gain global adoption, there is an increasing need to build social applications with abilities to detect and filter profane words.

Building applications that can detect and filter profanity could be one of the solutions to safer online social communication and interaction.

In this tutorial, we'll illustrate with code snippets how to build a profanity filter using Python better_profanity API and GraphQL.

What is Profanity

Profanity is the use of swear, rude, and offensive words in conversation. Profanity can be used to express a strong feeling of animosity or disapproval to someone or something.

A profanity filter is an application that detects, and filters words perceived as profane in an online communication channel.

Reasons to detect and filter profanity

To make online spaces safe for social interaction.
To automatically detect and filter unwanted content.
Detecting and filtering profanity improves user experience.
It builds healthy social spaces.

Detecting Profanity with better_profanity

Better-profanity is a blazingly fast Python library to detect and clean swear words. It supports custom word lists, safelists, detecting profanity in modified word spellings, Unicode characters (also called leetspeak), and even multi-lingual profanity detection.

To get started you'll need the following prerequisites:

Python installed on your machine
Basic knowledge of Python
Basic knowledge of GraphQL

Installing better_profanity library

To install the better_profanity library for our project, run the following command in your terminal:

 pip install better_profanity

In your Python project, create a profanity_filter.py file and add the following code snippets:

from better_profanity import profanity

profanity.load_censor_words()


def test_profanity(paragraph):
    print(profanity.censor(paragraph))

If you pass an offensive word as an argument to the function, as shown below:

test_profanity("Don't be fuck")

You would get the following result:

Don't be ****

Python better_profanity has a function that tells whether a string contains a swear word:

profanity.contains_profanity() # True | # False

Python better_profanity has a function that censors swear words with a custom character:

profanity.censor(word, '-')

The second argument in .censor('-') will be used to censor any swear word found in the first argument (word).

Building a GraphQL API for our Profanity Filter

Now we have the profanity filter working, let's build a GraphQL API for our filter and test it.

Installing Flask and GraphQL

To install Flask and GraphQL libraries in our application, on your terminal, run the following command:

pip install Flask Flask_GraphQL graphene

Next, we'll write our API GraphQl schema. To do that, create a schema.py file and add the following code:

import graphene
from better_profanity import profanity


class Outcome(graphene.ObjectType):
    paragraph = graphene.String()
    is_profane = graphene.Boolean()
    censored_paragraph = graphene.String()


class Query(graphene.ObjectType):
    detect_profanity = graphene.Field(Outcome, paragraph=graphene.String(
        required=True), character=graphene.String(default_value="*"))

    def resolve_detect_profanity(self, info, paragraph, character):
        is_profane = profanity.contains_profanity(paragraph)
        censored_paragraph = profanity.censor(paragraph, character)
        return Outcome(
            paragraph=paragraph,
            is_profane=is_profane,
            censored_paragraph=censored_paragraph
        )


profanity.load_censor_words()
schema = graphene.Schema(query=Query)

Next, let's configure our profanity filter to a server with an accessible URL. To do that, create a Python file, app.py, and add the following code to it:

from flask import Flask
from flask_graphql import GraphQLView
from schema import schema

app = Flask(__name__)
app.add_url_rule("/", view_func=GraphQLView.as_view("graphql",
                 schema=schema, graphiql=True))


if __name__ == "__main__":
    app.run(debug=True)

To run our application, run the following command in the terminal:

python app.py

If you do everything right, the server should start running, and your terminal should be like the one in the attached image below:

Now you can test your API by visiting this URL (http://127.0.0.1:5000/) as shown on the terminal.
Vising the URL, you'll see the GraphiQL interface as shown in the image below:

To test the API, execute the following query in the provided GraphQL interface:

{
  detectProfanity(paragraph: "Don't be an asshole", character: "%"){
    paragraph
    isProfane
    censoredParagraph
  }
}

And you'll get the following response:

{
  "data": {
    "detectProfanity": {
      "paragraph": "Don't be an asshole",
      "isProfane": true,
      "censoredParagraph": "Don't be an %%%%"
    }
  }
}

Conclusion

Building a safe social network for all users is an important factor to consider when building social applications. In this tutorial, we introduced the concept of profanity and how to detect and filter profane words in an application. We used the Python framework Flask and GraphQL to illustrate how to build a profanity filter API.

How to build a Cron Job using Node.js

Frank Joseph — Tue, 12 Nov 2024 10:13:55 +0000

Introduction
A cron job is a time-based task scheduler commonly used to automate repetitive tasks on a Linux or Unix-based system. These tasks can include running backups, updating databases, generating reports, and sending email reminders. In this article, we will discuss how to build a cron job using Node.js, a popular JavaScript runtime environment.

Node.js is an open-source, cross-platform JavaScript runtime that allows developers to build server-side applications using JavaScript. One of the key benefits of using Node.js for building cron jobs is that it can handle multiple concurrent connections and is highly scalable. This article will cover the basics of creating a cron job using Node.js, including setting up a schedule and running the job. We will also discuss some best practices for building and deploying cron jobs in a production environment. By the end of this article, you will have the knowledge and tools needed to build your cron job with Node.js.

What is a cron job?

A cron job is a scheduled task that runs automatically on a Unix-based operating system. The name "cron" is derived from the Greek word "Chronos" meaning time. Cron jobs automate repetitive tasks, such as sending emails, updating databases, and generating reports. They are typically run on a schedule, such as every day at a specific time or every hour.
Cron jobs are defined using a simple text file called the crontab which contains a list of commands to be executed and the schedule on which to execute them. Each line in the crontab represents a single cron job and follows a specific format. The format includes six fields, separated by spaces:

The minute (0-59).
The hour (0-23).
The day of the month (1-31).
The month (1-12).
The day of the week (0-7, where both 0 and 7 represent Sunday).
The command to be executed.

For example, the code snippet below illustrates how to schedule a task to run at every minute interval:

const cron = require("node-cron");

  cron.schedule("* * * * *", () => {
    console.log("running a task at every minute");
 })

The first argument passed into the cron.schedule function is the cron expression. You use the expression to specify the time at which the job should run.
The asterisks used in the code above represent a different unit of time and are part of the crontab syntax. Using five asterisks (* * * * ) is the default crontab for scheduling a task every five minutes. A cron job can also be configured to run at more specific intervals using special characters such as asterisks () and commas (,). For example, an asterisk (*) in the hour field would run the command every hour, while a comma-separated list of values (e.g. "1,15,30") would run the command at the specified minutes.
The second argument is the function (job) that gets executed when the expression in the first argument is passed.
The node-cron schedule function has an optional third argument, the configuration object used for job scheduling. The code below illustrates what the optional argument should look like:

{
    schedule: true,
    timezone: "Asia/Kolkata"

 }

The schedule by default is true, if you decide to set it to false, you’ll have to invoke the start method on the job object. A Job object is returned whenever the schedule function is called.
To execute the cron job, run the following command:

cron.start();

Cron jobs are a powerful tool for automating tasks on a server, but they must be used with caution. Incorrectly configured cron jobs can cause system crashes or data loss. It's important to test cron jobs thoroughly before deploying them in a production environment and to monitor their performance regularly.

Benefits of using Node.js for cron jobs

Node.js is a powerful JavaScript runtime built on Chrome's V8 JavaScript engine, which has become increasingly popular in recent years for building web applications and other types of server-side software. One of the most significant benefits of using Node.js for cron jobs is that it allows developers to use JavaScript on the server-side, making it easy to integrate with other technologies and services.

Another advantage of using Node.js for cron jobs is its ability to handle asynchronous code execution. Node.js is designed to handle multiple requests asynchronously, which is essential for running cron jobs that may take a long time to complete. With its event-driven architecture, Node.js can handle these tasks without blocking the execution of other code, ensuring that the server remains responsive and can handle other requests.

One other benefit of using Node.js for cron jobs is its vast ecosystem of packages and modules. Node.js has an extensive library of modules that can be easily integrated into a cron job, such as the popular node-cron package, which provides a simple and flexible way to schedule tasks. This allows developers to quickly and easily build cron jobs without having to start from scratch.

Furthermore, Node.js has become a popular choice for building web applications and APIs, and it's easy to use the same codebase for both the web application and the cron job. This makes it easy to share data between the cron job and the web application and to leverage existing code and libraries.

Additionally, Node.js has a large and active community, which means that it's easy to find support and resources for building cron jobs. There are many tutorials, articles, and forums available that can help developers get started with building cron jobs using Node.js.

Furthermore, Node.js is an excellent choice for building cron jobs, due to its ability to handle asynchronous code execution, a vast ecosystem of modules and packages, easy integration with web applications, and large community support. With Node.js, developers can quickly and easily build powerful and reliable cron jobs that can automate repetitive tasks, such as sending emails, updating databases, and generating reports.

Setting up a cron job

The Node.js Package Manager (NPM) registry contains a very useful cron job package, node-cron that can be used to schedule jobs that run at specific intervals.

I assume you already know how to install and set up a Node.js development environment, click on the link to install and set up your Node.js development environment.

To get started with this tutorial, create a new project folder by running this command on your terminal:

mkdir project-folder-name

On your terminal change the directory into the just created folder using the command below:

cd project-folder-name

On the root of the folder run the command below:

npm init -y

The command above creates amongst other files package.json file, which is useful for tracking your project dependencies and other necessary information.

Now install the node-cron package by running the command below:

npm i node-cron

This will install the node-cron module in the project. Check your package.json file to confirm this is installed.

Next, build a Node.js server and use node-cron to schedule a task. Let’s say for this example, we want to print to the console this statement “Zenrow technical writer” every minute.
Create a new file, cronapp.js.

In your new cronapp.js file, require the node-cron module.

const cron = require("node-cron")

Add the following lines of code to your cronapp.js file:

cron.schedule("* * * * *", () => {
    console.log("Zenrow technical writer");
 })

To run the script, you're in the correct directory and run the command below:

node cronapp.js

The expected output should look like seen below:

Zenrow technical writer
Zenrow technical writer
Zenrow technical writer
Zenrow technical writer
Zenrow technical writer
Zenrow technical writer
….
The output above represents what was printed to the console every minute before the server was stopped using CTRL C.

Sending Emails

Sending periodic emails is an important area of application for cron job. In this section, we will use the Node.js nodemailer and node-cron module to implement sending periodic email functionality. Nodemailer module support test account created with Ethereal Email.

To create a test account using Ethereal, click on the Create Ethereal Account button.

A test email will be generated automatically for you.

On your terminal, change the directory to the root folder using the command below:

cd project-folder-name

Install nodemailer module using the command below:

npm i nodemailer

Create a new file, cronEmail.js

Then require the necessary packages as shown below:

const cron = require("node-cron");
const nodemailer = require("nodemailer")

Next, add the following code:

const transporter = nodemailer.createTransport({
    host: "smtp.ethereal.email",
    port: 587,


    auth: {
        user: "demoemail@ethereal.email",
        pass: "demopassword"
    }
 })

The code above creates a mail transporter and sets the user and password.

NOTE: In live projects, you would use environment variables to store your password and any other sensitive information.

Next, add the following code snippet:

cron.schedule("24 13 * * *", () => {
    console.log("test")


    let data = {
        from: "demoemail@ethereal.email",
        to: "demoemail@ethereal.email",
        subject: "Test Email",
        text: "This is a test email"
    };


    transporter.sendMail(data, (err, info) =>{
        if(err){
            throw err;
        }else{
            console.log("Email sent");
        }
    })
 })

The code snippet above schedules an email to be sent at (“24 13 * * *”), the pattern means emails will be sent at 1:24 pm every day. The code will send an email with the following contents:

Subject: “Test Email”
Text: “This is a test email”

To the Ethereal test email account.

We have covered how to use a cron job to schedule tasks, and send emails, the following section will illustrate how to delete files with a cron job. This use case becomes handy when you want to routinely delete a specific log file from the server at a particular interval.

Create a log file named:

zenrow.log

Then, add a message:

Zenrow logs

Create a new cronDelete.js file

Inside the cronDelete.js file, require the fileSystem (fs) and node-cron modules:

const cron = require("node-cron")
const fs = require("fs")

Next, add the following code snippets:

cron.schedule("48 14 * * *", function() {
    console.log("Running Cron Job");
    fs.unlink("Zenrow.log", (err) => {
      if (err) throw err;
      console.log('Log file successfully deleted');
    });
  });

The schedule pattern: “48 14 * * *”

Defines a value for minutes and hours as 48 and 14 respectively
It didn’t define the day
It didn’t define the day of the week or Month

Note: You can set the cron pattern to suit your needs.

Run the script with the following command:

node cronDelete.js

The script will execute at 14:48PM and the zenrow.log will be deleted.

Some best practices for building and deploying a cron job

Test cron jobs thoroughly before deploying them to a production environment. This will help ensure that they are working as expected and won't cause any issues when they are in live environment.
Use a centralized logging system to collect and aggregate log data from cron jobs. This will make it easier to monitor and troubleshoot any issues that arise. You can learn more about how to use airplane to monitor cron jobs here.
Keep your cron jobs as simple as possible and do not include any unnecessary logic or functionality. This will help ensure that they are easy to maintain and debug
.
Use a notification system to alert you when a cron job fails or when it completes successfully.
Use a monitoring tool to keep an eye on the performance and uptime of your cron jobs. This will help you quickly identify and resolve any issues that may arise.
Use a scheduler like Kubernetes cronjob to schedule the cron job, rather than using the built-in cron daemon. This allows for better scalability and fault tolerance.

Common issues with cron jobs

Cron jobs are a powerful tool for automating tasks on a server, but they can also come with some challenges and potential issues. Some of the most common issues with cron jobs include:

Lack of monitoring: If there is no proper monitoring, it may be difficult to detect when a cron job has failed or is not running correctly. This can lead to data inconsistencies or delays in completing important tasks.
Cron job failure: Cron jobs can fail for various reasons such as network issues, missing dependencies, or bugs in the code. It is important to have proper error handling and logging in place to detect and diagnose any issues that may arise.
Overlapping cron jobs: Another common issue is that multiple cron jobs scheduled to run at the same time can lead to resource conflicts and potential data inconsistencies.
Security risks: Cron jobs can also pose security risks if not properly configured. For example, a cron job that runs with root permissions can be exploited by malicious actors to gain access to sensitive information.

Strategies for troubleshooting cron jobs

Troubleshooting cron jobs can be a challenging task, but with the right strategies, you can quickly identify and resolve any issues. Here are some strategies for troubleshooting cron jobs:

Check the cron log: Most systems have a log that records when cron jobs run and any errors that occur. The location of the log file varies depending on the operating system.
Check the cron schedule: Make sure that the cron schedule is correct and that the job is scheduled to run at the correct time.
Check the environment variables: Some cron jobs rely on environment variables, so make sure that the necessary environment variables are set and that they have the correct values.
Before deploying to production, test the script manually: Try running the script manually from the command line to see if it runs correctly and to check for any errors.
Check for dependencies: Ensure that all necessary dependencies for the command or script specified in the cron job are installed and configured correctly.
Schedule the job with different intervals: Try scheduling it with different intervals, like every minute or every 5 minutes, to check if it works fine.
By following these strategies, you can quickly identify and fix problems with your cron jobs, ensuring that they run smoothly and efficiently.

Conclusion

Building a cron job with Node.js is a simple and efficient way to automate repetitive tasks in your applications. By using the node-cron package, you can easily schedule tasks to run at specified intervals, making it easy to keep your applications running smoothly. This article has provided a step-by-step guide for building a cron job with Node.js, including code snippets, and also discussed the strategies for troubleshooting cron jobs. With this knowledge, you can now easily automate tasks in your Node.js applications, freeing up valuable time and resources.

Using Node.js for Ecommerce Platforms

Frank Joseph — Mon, 30 Jan 2023 09:06:28 +0000

Introduction

Node.js is a JavaScript server-side runtime development environment. It is built on Chrome’s V8 engine; it gives software developers the ability to write JavaScript code that runs on the server side. It is an open source and cross-platform server-side environment developer by Ryan Dahl.

Node.js is a powerful, open-source, JavaScript-based platform that allows developers to build high-performance and scalable network applications. One of the areas where Node.js shines is ecommerce development. With Node.js, developers can build fast, efficient, and dynamic ecommerce applications that can handle a large number of products, customers, and transactions. However, as with any technology, there are pros and cons to using Node.js for ecommerce.

In this guide, we will explore in-depth the pros and cons of using Node.js for e-commerce. Whether you're an experienced ecommerce developer or just getting started, this guide will provide you with the knowledge you need to decide if Node.js is suitable for your next e-commerce store development.

What is Node.js?

How Node.js Works

Node.js applications are asynchronous and non-blocking by default. In this architecture, a single thread is used to manage multiple requests. Its event-driven nature contributes to its speed when used to develop applications. Some of Node.js features are:

Single-Threaded Architecture: Node.js uses single-threaded architecture and event looping. When compared with other server-side languages that create limited threads to handle requests, Node.js is considered more scalable as it handles requests in a non-blocking manner.

Asynchronous by Design: Node.js APIs are asynchronous by design, meaning Node.js handles requests asynchronously. It doesn't have to wait for one request to finish before it moves on to the next one.

Node Package Manager (NPM): It is an online registry for Node.js packages. This repository contains more than a million different packages useful for the development of Node.js applications. Anyone can access this registry and install packages for their application.

Event-Driven Mechanism: This unique feature of Node.js helps make the program as simple as possible and synchronizes the occurrence of multiple events. The event-driven mechanism consists of a callback function and an event loop.

Challenges in Ecommerce

In recent years, ecommerce has gained a lot of attention and competition is becoming intense. One metric that would contribute to success is the nature of responsiveness of your applications. This is a clear reason why it is important to choose tools that would give users a better experience.

Some challenges encountered within the ecommerce sectors are as follows:

Technology:

Technology changes fast, so developers have constantly stay inform with the changes. Some programming languages do not entirely support both frontend and backend development, and so there is a need to use different languages for the frontend and backend.
Programming language barrier

Some programming languages are heavy and contribute to lagging in an ecommerce application or increased application load time.
Expert Experience:

Building any complex application requires expert skills and domain knowledge

Pros of using Node.js for Ecommerce

Using Node.js to build an ecommerce store helps to solve some challenges with ecommerce listed above. Node.js helps developers to build high-performance data-streaming web applications. The points shows node.js ecommerce pros:

Node.js is Open Source:

As an open source software, Node.js enjoys community support. When building an ecommerce web app with Node.js, you’re sure to get support from the community (other experienced developers) whenever you run into challenges.
Fast Development:

One key Node.js advantage is that development is fast. This is due to the ability to reuse existing open-source tools within your application which saves time on features without having to reinvent the wheel. Several Node.js packages can be downloaded and reused to build an online store.
Cross-Platform Compatibility:

Node.js is a cross-platform development environment and can be used to build websites and applications that can work on different types of computers.
Full-stack development:

Building an ecommerce application with Node.js means that you can use a single programming language to build both the backend and frontend. Developers need only to know JavaScript to be able to build an online store with Node.js.
Scalability and Performance: The non-blocking and event-driven feature of Node.js make it a scalable option for building ecommerce. It directly interacts with the V8 JavaScript engine, enabling easy compilation into machine codes with high efficiency and speed.

Cons of Using Node.js for Ecommerce

As with most programming languages, Node.js has garnered a lot of support and huge acceptance, maybe because of the growing JavaScript ecosystem. Even with its huge community support, Node.js has some drawbacks, and they affect how it is used in ecommerce applications:

Poor Dependency Management:

Numerous tools in the npm registry are either of poor quality or need to be fully documented/tested. Additionally, the registry's design doesn't allow it to present the tools according to their ranking or quality.
Asynchronous programming can be difficult:

Node.js uses an asynchronous programming model, which can make it more challenging for developers to write and maintain code, especially if they are not familiar with this programming paradigm.
High server resource usage: Node.js is known to use more server resources than other server-side technologies, which can be a concern for ecommerce websites that need to handle a large number of requests and transactions. This can increase hosting costs and make it more difficult to achieve optimal performance.

Use Medusa, a Node.js Ecommerce Platform

Medusa is an open source composable commerce engine that’s a viable option for developing ecommerce web applications. One significant distinctive attribute of Medusa is that it offers merchants limitless customization opportunities.

Medusa is divided into three components, namely:

Medusa server: This section is the backend that exposes REST APIs.
Admin Panel: This is where developers or platform users can control and configure their store's features.
Frontend: This section can be created using any framework, Nextjs, or static site generators like Gatsby. This is the frontend or user-facing side of the Medusa platform.

Advantages of Using Medusa

Customization

Medusa is built with customization in mind. Although it provides customizable features out-of-the-box, this is possible because of the composable open-source architecture.

Medusa includes more customization options for merchants. For example, developers can customize the data layer or backend of a Medusa store based on business preference to better serve their customers. For example, users can integrate with Strapi, Contentful, or any other CMSes.

Plugins allow developers to implement custom features or integrate third-party services like payment into medusa. You can create or use existing plugins to integrate your store with third-party services.

Medusa is open source

This means that almost anyone can access its source code. It enjoys a huge developer community support and collaboration, this is very important as the software is tested by a community of developers. Ownership of codebase and customization ability. Medusa is complete free to use.

Maintenance and Scalability

Medusa is built to scale to meet customers’ needs. Any E-commerce store built with Medusa is maintainable and scalable. Medusa is lightweight to maintain, easy to use and it is capable of scaling with business growth to meet customers’ needs.

Site performance

Medusa’s headless architecture decouples the frontend from the backend. The importance of this kind of architecture is that the site loads faster since it loads independently of the backend and only interacts with it to retrieve or add data.

Conclusion

Node.js is a great tool for developing high-performing web applications. This guide explicitly highlighted what Node.js is, how it works, ecommerce, and the pros and cons of using Node.js for ecommerce applications. To get started with Medusa e-commerce engine, click here.