LCS Ajax

A secure and efficient JavaScript library for handling AJAX requests with nonce-based CSRF protection.

Table of Contents

• Introduction
• Features
• Installation
• Quick Start
  • Basic Usage
  • Handling FormData (File Uploads)
  • Adding Custom Headers
  • GET Requests
• Security & CSRF Protection
• Advanced Usage
  • Fetching a Nonce Manually
  • Customizing the Nonce Name
  • Handling API Responses
• Error Handling
• API Reference
• Development & Contribution
• License
• Support

Introduction

lcs_ajax is a lightweight JavaScript library designed for making secure AJAX requests with nonce-based CSRF protection. It simplifies communication between the frontend and backend while ensuring security and flexibility.

Built using the Fetch API, lcs_ajax supports:

• JSON & FormData (file uploads)
• Custom headers
• Automatic nonce retrieval for security
• One request at a time to prevent conflicts
• Easy API integration

Features

✅ Secure AJAX Requests – Includes nonce-based CSRF protection to prevent cross-site request forgery.
✅ Easy Integration – Works seamlessly with APIs and web applications.
✅ Automatic Nonce Handling – Fetches and attaches a nonce for extra security.
✅ Supports JSON & FormData – Works with structured JSON data and file uploads.
✅ Asynchronous & Efficient – Uses modern async/await with Fetch API for speed and reliability.
✅ Prevents Concurrent Requests – Ensures that only one AJAX request runs at a time to avoid conflicts.
✅ Lightweight – Minimal dependencies, just pure JavaScript.

Installation

You can use lcs_ajax in your project in multiple ways.

1. Install via NPM

npm install lcs_ajax

Then, import it in your JavaScript file:

import { lcsSendAjaxRequest } from 'lcs_ajax';

2. Include via CDN

Add the following script to your HTML file:

<script src="https://cdn.jsdelivr.net/npm/lcs_ajax/dist/la.min.js"></script>

3. Manually Download

Download la.min.js and include it in your project:

<script src="path/to/la.min.js"></script>

Quick Start

Basic Usage

Sending a simple AJAX request:

const requestData = { name: 'John Doe', email: '[email protected]' };

lcsSendAjaxRequest(requestData, 'https://example.com/api', 'POST')
    .then(response => console.log('Success:', response))
    .catch(error => console.error('Error:', error));

Handling FormData (File Uploads)

To send file uploads, use FormData:

const formData = new FormData();
formData.append('file', document.querySelector('#fileInput').files[0]);

lcsSendAjaxRequest(formData, 'https://example.com/upload', 'POST')
    .then(response => console.log('File uploaded:', response))
    .catch(error => console.error('Upload failed:', error));

Adding Custom Headers

const headers = { Authorization: 'Bearer my-token' };

lcsSendAjaxRequest({ data: 'test' }, 'https://example.com/secure', 'POST', headers)
    .then(response => console.log('Success:', response))
    .catch(error => console.error('Error:', error));

GET Requests

lcsSendAjaxRequest({}, 'https://example.com/api/data', 'GET')
    .then(response => console.log('Fetched Data:', response))
    .catch(error => console.error('Fetch error:', error));

Security & CSRF Protection

lcs_ajax automatically retrieves a nonce before sending a request. This prevents CSRF attacks by ensuring only authorized requests are executed.

How it works:

1. The library fetches a nonce from the server.
2. The nonce is attached to every AJAX request.
3. The server validates the nonce before processing the request.

By default, lcs_ajax looks for a meta tag containing the AJAX object:

<meta name="lcs_ajax_object" content='{"ajaxurl": "https://example.com/api", "nonce": "secure-token"}'>

Advanced Usage

Fetching a Nonce Manually

You can manually fetch a nonce before making a request:

lcsGetNonce({ nonce_name: 'lcs_ajax_nonce' }, 'https://example.com/api')
    .then(nonce => console.log('Fetched Nonce:', nonce))
    .catch(error => console.error('Nonce error:', error));

Customizing the Nonce Name

You can specify a custom nonce name:

lcsSendAjaxRequest({ data: 'test', nonce_name: 'custom_nonce' }, 'https://example.com/api', 'POST')
    .then(response => console.log('Success:', response))
    .catch(error => console.error('Error:', error));

Handling API Responses

The function returns a Promise, allowing structured error handling:

lcsSendAjaxRequest({ username: 'testuser' }, 'https://example.com/login', 'POST')
    .then(response => {
        if (response.success) {
            console.log('Login successful!');
        } else {
            console.error('Login failed:', response.message);
        }
    })
    .catch(error => console.error('AJAX error:', error));

Error Handling

Common Errors

| Error | Cause | |-------|-------| | Network Errors | The server is unreachable. | | Invalid JSON Response | The response is not valid JSON. | | Failed to verify client! | Nonce retrieval failed | | Request failed due to server error! | Network/server issue | | Expected JSON but received: text/html | API returned invalid response |

To handle errors properly:

lcsSendAjaxRequest({ email: 'invalid' }, 'https://example.com/register', 'POST')
    .catch(error => console.error('Error:', error.message));

API Reference

lcsSendAjaxRequest(data, url, method, headers)

Sends an AJAX request.

| Parameter | Type | Default | Description | |-----------|------|---------|-------------| | data | Object | FormData | {} | The request payload (JSON or FormData). | | url | string | lcs_ajax_object.ajaxurl | The request endpoint. | | method | string | 'POST' | HTTP method (GET, POST, etc.). | | headers | Object | {} | Additional request headers. | | Returns | Promise<Object> | - | Resolves with the response data. |

Development & Contribution

Want to improve lcs_ajax? Contributions are welcome!

🔹 Fork the repository
🔹 Create a feature branch (git checkout -b feature-name)
🔹 Commit changes (git commit -m "Add feature")
🔹 Push and create a Pull Request

See CONTRIBUTING.md for details.

License

This project is licensed under the MIT License. See the LICENSE file for details.

Support

💬 Found a bug or need help? Open an issue at:
📌 GitHub Issues

📧 Contact: [email protected], [email protected]