ZelApi is a powerful and versatile JavaScript/TypeScript library designed to simplify HTTP requests to the ZelApi service. It provides an intuitive and flexible interface for developers, featuring universal parameter handling, support for multiple response types, and a secure method for managing your API key. Whether you're building a small script or a large application, ZelApi helps you interact with the API efficiently.

Features

• Modern JavaScript Support: Built with ESNext modules and TypeScript, providing a modern development experience with type safety and autocompletion.
• Dual API Versions: Comes with two clients, ZelApiv1 (free, no API key) and ZelApiv2 (requires an API key), for different usage needs.
• Flexible Parameter Handling: Send parameters as a simple string for text-based endpoints or as a detailed object for more complex requests.
• Multiple Response Formats: Effortlessly handle different data types by specifying the response format:
  • json(): For structured data.
  • text(): For plain text responses.
  • buffer(): For binary data like images, videos, or other files.
• Secure by Design: API keys are handled as URL parameters for authenticated requests, and the library encourages best practices for key management.
• Lightweight and Minimal Dependencies: Keeps your project lean with a small footprint and minimal external dependencies.
• Clear Error Handling: Provides straightforward error messages to help you debug issues quickly.

Installation

You can install zelapi using your favorite package manager:

# Using npm
npm install zelapi

# Using yarn
yarn add zelapi

# Using pnpm
pnpm add zelapi

How to Use

ZelApi offers two clients: ZelApiv1 and ZelApiv2.

• ZelApiv1: Connects to zelapioffciall.koyeb.app. It's free to use and does not require an API key.
• ZelApiv2: Connects to zelapioffciall.dpdns.org. It requires an API key for authenticated access.

ZelApiv1 Usage (No API Key)

Here's a simple example using ZelApiv1 to fetch a random quote.

import { ZelApiv1 } from "zelapi";

const zel = new ZelApiv1();

async function getQuote() {
  try {
    const quote = await zel.text("/random/quote");
    console.log("Random Quote:", quote);
  } catch (error) {
    console.error("Error fetching quote:", error.message);
  }
}

getQuote();

ZelApiv2 Usage (API Key Required)

To use ZelApiv2, you must provide an API key. It is highly recommended to store your API key in an environment variable for security.

This example shows how to download a random meme image and save it to a file.

import { ZelApiv2 } from "zelapi";
import fs from "fs";
import path from "path";

// Load API key from environment variables for security
const zel = new ZelApiv2({
  apiKey: process.env.ZELAPI_KEY || "YOUR_API_KEY_HERE",
});

async function downloadMeme() {
  try {
    console.log("Downloading a random meme...");
    const memeBuffer = await zel.buffer("/random/meme");
    
    const filePath = path.join(process.cwd(), "meme.jpg");
    fs.writeFileSync(filePath, memeBuffer);
    
    console.log(`Meme saved successfully to ${filePath}!`);
  } catch (error) {
    console.error("Error downloading meme:", error.message);
  }
}

downloadMeme();

Universal Parameters

You can pass parameters as an object or a single string, depending on the endpoint's requirements.

Object Parameters

This is useful for endpoints that require multiple parameters.

import { ZelApiv1 } from "zelapi";

const zel = new ZelApiv1();

async function search() {
  try {
    const results = await zel.json("/search/pinterest", {
      q: "aesthetic wallpaper",
    });
    console.log(results);
  } catch (error) {
    console.error("Error searching:", error);
  }
}

search();

String Parameter

If you pass a string as the second argument, it will be treated as the text parameter, which is a common requirement for many endpoints.

import { ZelApiv1 } from "zelapi";

const zel = new ZelApiv1();

async function stylizeText() {
  try {
    const styled = await zel.text("/style/fancy", "Hello World");
    console.log(styled);
  } catch (error) {
    console.error("Error stylizing text:", error);
  }
}

stylizeText();

Error Handling

If a request fails, zelapi will throw an error. You should wrap your API calls in a try...catch block to handle potential errors gracefully.

import { ZelApiv1 } from "zelapi";

const zel = new ZelApiv1();

async function fetchData() {
  try {
    // This endpoint does not exist, so it will trigger an error
    const data = await zel.json("/some/invalid-endpoint");
    console.log(data);
  } catch (error) {
    // Handle the error
    console.error("An error occurred:", error.message);
    // Example error message: "ZelApiError 404: Not Found"
  }
}

fetchData();

Contributing

Contributions are welcome! Please read our Contributing Guidelines and Code of Conduct before submitting a pull request.

Security

If you discover a security vulnerability, please report it to us by following the instructions in our Security Policy.

License

This project is licensed under the MIT License.