[![ZelApi](./media/image.jpg)](https://zelapioffciall.koyeb.app)
<p align="center">
  <a href="https://www.npmjs.com/package/zelapi"><img src="https://img.shields.io/npm/v/zelapi.svg?style=flat&logo=npm" alt="NPM Version"></a>
  <a href="https://www.npmjs.com/package/zelapi"><img src="https://img.shields.io/npm/dt/zelapi.svg?style=flat&logo=npm" alt="NPM Downloads"></a>
  <img src="https://img.shields.io/badge/Node.js-339933?style=flat&logo=nodedotjs&logoColor=white" alt="Node.js">
  <img src="https://img.shields.io/badge/TypeScript-3178C6?style=flat&logo=typescript&logoColor=white" alt="TypeScript">
</p>

**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:

```bash
# 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.

```javascript
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.

```javascript
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.

```javascript
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.

```javascript
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.

```javascript
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](CONTRIBUTING.md) and [Code of Conduct](CODE_OF_CONDUCT.md) 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](SECURITY.md).

## License

This project is licensed under the [MIT License](LICENSE).