nekosia.js 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Nekosia
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,130 @@
+<div align="center">
+    <h1>🖼️ Nekosia.js API — Random Anime Images</h1>
+</div>
+
+Nekosia.js is a Node.js module that provides easy access to the Nekosia API, a rich source of anime-themed images.
+The API offers a wide range of categories, allowing you to quickly and flexibly search for images according to your preferences and needs.
+You decide what images you want to retrieve, which makes our API stand out from others.
+
+But that's not all! The API also supports sessions (based on user ID or IP address), helping to avoid repeated images.
+
+<div align="center">
+    <a href="https://www.npmjs.com/package/nekosia.js">
+        <img src="https://img.shields.io/npm/dm/nekosia.js" alt="npm downloads">
+    </a>
+    <a href="https://github.com/Nekosia-API/nekosia.js/issues">
+        <img src="https://img.shields.io/github/issues/Nekosia-API/nekosia.js" alt="Issues">
+    </a>
+    <a href="https://github.com/Nekosia-API/nekosia.js/commits/main">
+        <img src="https://img.shields.io/github/last-commit/Nekosia-API/nekosia.js" alt="Last commit">
+        <img src="https://img.shields.io/github/commit-activity/w/Nekosia-API/nekosia.js" alt="Commit activity">
+        <img src="https://img.shields.io/github/languages/code-size/Nekosia-API/nekosia.js" alt="Code size">
+    </a>
+</div>
+
+
+## 🔍 Key Features of the API
+- **Wide range of categories:** Nekosia API offers [virtually every kind of anime graphic](https://nekosia.cat/documentation?page=api-endpoints#main-categories), not limited to neko images.
+- **High image quality:** All images are carefully selected and checked for quality and appropriateness.
+- **Sessions:** The API supports sessions (based on ID or IP address), which helps avoid duplicate images.
+- **Dominant colors:** The API returns a palette of dominant colors for each image.
+- **Image compression:** JSON responses include a link to a compressed image that is much smaller than the original. This can be useful if you want images to load quickly on client devices without sacrificing quality.
+- **Security:** Nekosia API ensures that all provided content is free from NSFW material, making it one of the most trusted sources of anime-themed images.
+
+...and that’s not all!
+
+
+## 📘 Own Booru
+Nekosia also offers its own [Booru](https://nekosia.cat/booru), allowing you to browse images returned by the API.
+Users can edit image information, such as tags, which are crucial for us.
+
+
+## 📄 Documentation
+Check out the [official documentation](https://nekosia.cat/documentation) to learn more.
+
+
+## 📦 Instalacja
+To install the Nekosia.js module, use the following command:
+
+```bash
+npm install neksosia.js
+```
+
+
+## 🔤 Lista tagów
+You can find the main image categories [here](https://nekosia.cat/documentation?page=api-endpoints#tags-and-categories).
+The full list of tags is available [on the Booru site](https://nekosia.cat/booru/tags).
+
+
+## 🤔 How to Use?
+
+### Simple Example
+```js
+const { NekosiaAPI } = require('nekosia.js');
+
+(async () => {
+	const response = await NekosiaAPI.fetchImages('catgirl');
+	console.log(response); // Sample response: https://nekosia.cat/documentation?page=api-endpoints#example-response
+})();
+```
+
+
+### IP-based Sessions
+In this example, we used an IP-based session. What does this mean? Thanks to this solution, a user with a specific IP address will not encounter duplicates when randomly selecting images.
+
+```js
+const { NekosiaAPI } = require('nekosia.js');
+
+(async () => {
+	const response = await NekosiaAPI.fetchImages('catgirl', {
+		session: 'ip',
+		count: 1,
+		additionalTags: [],
+		blacklistedTags: []
+	});
+
+	console.log(response);
+})();
+```
+
+### ID-based Sessions
+You can also use `id`, but this will require providing a user identifier (e.g., from Discord). Pass this information in `id` as a string.
+
+```js
+const { NekosiaAPI } = require('nekosia.js');
+
+(async () => {
+	const response = await NekosiaAPI.fetchImages('catgirl', {
+		session: 'id',
+		id: '561621386765971781',
+		count: 1,
+		additionalTags: [],
+		blacklistedTags: []
+	});
+
+	console.log(response);
+})();
+```
+
+### See more
+https://github.com/Nekosia-API/nekosia.js/tree/main/examples
+
+
+## Versions
+```js
+const { NekosiaVersion } = require('nekosia.js');
+
+(async () => {
+	console.log(NekosiaVersion.module); // Returns the installed module version
+	console.log(await NekosiaVersion.api()); // Returns the current API version used by the module
+})();
+``` 
+
+
+## ⭐ » Thanks
+If you find the API or this module useful, consider giving a star to the [repository](https://github.com/sefinek24/nekosia.js).
+If you have questions or issues, create a new [Issue](https://github.com/Nekosia-API/nekosia.js/issues/new) or join the [serwer Discord](https://discord.gg/pba76vJhcP).
+
+
+## 📑 » MIT License
+Copyright 2023-2024 © by [Sefinek](https://sefine.net). All rights reserved.

package/examples/basicUsage.js

@@ -0,0 +1,12 @@
+const { NekosiaAPI } = require('../index.js');
+
+(async () => {
+	const response = await NekosiaAPI.fetchImages('foxgirl', {
+		session: 'ip',
+		count: 1,
+		additionalTags: ['cute', 'sakura', 'cherry-blossom'],
+		blacklistedTags: ['beret']
+	});
+
+	console.log(response);
+})();

package/examples/dynamicCategoryFetch.js

@@ -0,0 +1,15 @@
+const { NekosiaAPI } = require('../index.js');
+
+const fetchImages = async (category, options = {}) => {
+	try {
+		const response = await NekosiaAPI.fetchImages(category, options);
+		console.log(`${category.toUpperCase()}:`, response);
+	} catch (err) {
+		console.error(`Error fetching ${category} images:`, err);
+	}
+};
+
+(async () => {
+	await fetchImages('catgirl');
+	await fetchImages('foxgirl', { session: 'id', id: 'user123', count: 2 });
+})();

package/examples/fetchShadowImages.js

@@ -0,0 +1,6 @@
+const { NekosiaAPI } = require('../index.js');
+
+(async () => {
+	const response = await NekosiaAPI.fetchShadowImages({ session: 'ip', count: 1, additionalTags: ['cute', 'blue-hair'] });
+	console.log(response);
+})();

package/examples/version.js

@@ -0,0 +1,6 @@
+const { NekosiaVersion } = require('../index.js');
+
+(async () => {
+	console.log(NekosiaVersion.module);
+	console.log(await NekosiaVersion.api());
+})();

package/index.js

@@ -0,0 +1,78 @@
+const https = require('./services/https.js');
+const BASE_URL = 'https://api.nekosia.cat';
+const API_URL = `${BASE_URL}/api/v1`;
+
+class NekosiaAPI {
+	buildQueryParams(options = {}) {
+		return Object.entries(options)
+			.filter(([, value]) => {
+				if (typeof value === 'string' && value.includes(',')) {
+					throw new Error('A single tag in the string cannot contain commas. Please use an array instead.');
+				}
+
+				return value != null && value !== '' && (!Array.isArray(value) || value.length > 0);
+			})
+			.map(([key, value]) => `${encodeURIComponent(key)}=${value}`)
+			.join('&');
+	}
+
+	async makeHttpRequest(endpoint) {
+		try {
+			return await https.get(endpoint);
+		} catch (err) {
+			console.error(`HTTP request failed for endpoint ${endpoint}: ${err.message}`);
+			throw err;
+		}
+	}
+
+	async fetchImages(category, options = {}) {
+		if (!category) {
+			throw new Error('The image category is required. For example, use fetchImages(\'catgirl\').');
+		}
+
+		if (options.session && !['id', 'ip'].includes(options.session)) {
+			throw new Error('The `session` setting can contain only the following values `id` and `ip`, both as strings.');
+		}
+
+		if (!options.session && options.id) {
+			throw new Error('`id` is not required if the session is `null` or `undefined`');
+		}
+
+		const queryString = this.buildQueryParams({
+			session: null,
+			id: null,
+			count: 1,
+			additionalTags: [],
+			blacklistedTags: [],
+			...options
+		});
+
+		return this.makeHttpRequest(`${API_URL}/images/${category}?${queryString}`);
+	}
+
+	async fetchShadowImages(options = {}) {
+		if (!Array.isArray(options.additionalTags) || options.additionalTags.length === 0) {
+			throw new Error('`additionalTags` must be a non-empty array for the shadow category');
+		}
+
+		return this.fetchImages('shadow', options);
+	}
+
+	async fetchById(id) {
+		if (!id) throw new Error('`id` parameter is required');
+
+		return this.makeHttpRequest(`${API_URL}/getImageById/${id}`);
+	}
+}
+
+const NekosiaVersion = {
+	module: https.version,
+	api: async () => {
+		return await https.get(BASE_URL);
+	}
+};
+
+module.exports = {
+	NekosiaAPI: new NekosiaAPI(),
+	NekosiaVersion
+};

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "nekosia.js",
+  "version": "0.1.0",
+  "description": "A simple wrapper for the Nekosia API that provides easy access to random anime images. Enhance your projects with the magic of anime and a touch of feline charm meow~~! Discover why switching to Nekosia is the purrfect choice!",
+  "keywords": [
+    "anime",
+    "anime-api",
+    "anime-art",
+    "anime-characters",
+    "anime-gifs",
+    "anime-images",
+    "anime-library",
+    "api-wrapper",
+    "cat",
+    "cat-ears",
+    "catgirl",
+    "catgirls",
+    "chibi",
+    "cute-animals",
+    "feline",
+    "image-api",
+    "japan",
+    "javascript",
+    "js-library",
+    "kawaii",
+    "manga",
+    "moe",
+    "neko",
+    "neko-girls",
+    "nekos",
+    "nekosia",
+    "nekosia-api",
+    "otaku",
+    "random-anime",
+    "typescript",
+    "waifu"
+  ],
+  "homepage": "https://nekosia.cat",
+  "bugs": {
+    "url": "https://github.com/Nekosia-API/nekosia.js/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Nekosia-API/nekosia.js.git"
+  },
+  "license": "ISC",
+  "author": "Sefinek <contact@sefinek.net> (https://sefinek.net)",
+  "main": "index.js",
+  "typings": "types/index.d.ts",
+  "scripts": {
+    "test": "jest",
+    "up": "ncu -u && npm install && npm update && npm audit fix"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.9.0",
+    "globals": "^15.9.0",
+    "jest": "^29.7.0"
+  }
+}

package/services/https.js

@@ -0,0 +1,45 @@
+const https = require('https');
+const { name, version, homepage, devDependencies } = require('../package.json');
+
+const headers = {
+	'User-Agent': `Mozilla/5.0 (compatible; ${name}/${version}; +${homepage})${process.env.JEST_WORKER_ID ? ` jest/${devDependencies.jest.replace(/^[^0-9]*/, '')}` : ''}`,
+	'Accept': 'application/json',
+	'Content-Type': 'application/json',
+	'Cache-Control': 'no-cache',
+	'Connection': 'keep-alive',
+	'DNT': '1'
+};
+
+const makeRequest = url => new Promise((resolve, reject) => {
+	const req = https.get(url, { headers, timeout: 9000 }, res => {
+		let data = '';
+
+		res.on('data', chunk => {
+			data += chunk;
+		});
+
+		res.on('end', () => {
+			if ((res.statusCode < 200 || res.statusCode >= 300) && res.statusCode !== 400) {
+				return reject(new Error(`HTTP Status Code: ${res.statusCode}`));
+			}
+
+			try {
+				const parsedData = JSON.parse(data);
+				resolve(parsedData);
+			} catch (err) {
+				reject(new Error(`Failed to parse JSON: ${err.message}. Response: ${data}`));
+			}
+		});
+	});
+
+	req.on('error', err => reject(new Error(`Request error: ${err.message}`)));
+
+	req.on('timeout', () => {
+		req.destroy();
+		reject(new Error('Timeout error'));
+	});
+
+	req.end();
+});
+
+module.exports = { get: makeRequest, version };

package/test/api.test.js

@@ -0,0 +1,110 @@
+const { NekosiaAPI } = require('../index.js');
+
+describe('NekosiaAPI (API Tests)', () => {
+
+	describe('fetchImages', () => {
+		it('should fetch images for the given category', async () => {
+			const res = await NekosiaAPI.fetchImages('catgirl', { count: 1 });
+
+			expect(res).toBeInstanceOf(Object);
+			expect(res.success).toBe(true);
+			expect(res.status).toBe(200);
+
+			expect(res).toHaveProperty('category');
+			expect(res).toHaveProperty('id');
+			expect(res).toHaveProperty('image');
+
+			expect(res.image).toHaveProperty('original');
+			expect(res.image).toHaveProperty('compressed');
+			expect(res.image.original).toHaveProperty('url');
+			expect(res.image.original).toHaveProperty('extension');
+			expect(res.image.compressed).toHaveProperty('url');
+			expect(res.image.compressed).toHaveProperty('extension');
+
+			expect(res.metadata).toHaveProperty('original');
+			expect(res.metadata.original).toHaveProperty('width');
+			expect(res.metadata.original).toHaveProperty('height');
+			expect(res.metadata.original).toHaveProperty('size');
+			expect(res.metadata.original).toHaveProperty('extension');
+
+			expect(res.metadata).toHaveProperty('compressed');
+			expect(res.metadata.compressed).toHaveProperty('width');
+			expect(res.metadata.compressed).toHaveProperty('height');
+			expect(res.metadata.compressed).toHaveProperty('size');
+			expect(res.metadata.compressed).toHaveProperty('extension');
+
+			expect(res).toHaveProperty('tags');
+			expect(res.tags).toBeInstanceOf(Array);
+			expect(res.tags.length).toBeGreaterThan(0);
+
+			expect(res).toHaveProperty('rating');
+			expect(res).toHaveProperty('source');
+			expect(res.source).toHaveProperty('url');
+		});
+
+		it('should return an error for an invalid category', async () => {
+			const res = await NekosiaAPI.fetchImages('invalid-category', { count: 1 });
+
+			expect(res.success).toBe(false);
+			expect(res.status).toBe(400);
+		});
+
+		it('should return a specified number of images', async () => {
+			const res = await NekosiaAPI.fetchImages('catgirl', { count: 3 });
+
+			expect(res).toBeInstanceOf(Object);
+			expect(res.success).toBe(true);
+			expect(res.status).toBe(200);
+			expect(res.count).toBe(3);
+			expect(res).toHaveProperty('images');
+			expect(res.images).toBeInstanceOf(Array);
+			expect(res.images.length).toBe(3);
+		});
+	});
+
+	describe('fetchShadowImages', () => {
+		it('should handle no images found for shadow category with additional tags', async () => {
+			const res = await NekosiaAPI.fetchShadowImages({ count: 1, additionalTags: ['wTbf8J0TirS6a4fO5uyKcRazZOlO5h6o', 'xX9f9pwDAgsM3Li1LwsJ3tXQfGKW4WA0'] });
+
+			expect(res.success).toBe(false);
+			expect(res.status).toBe(400);
+		});
+
+		it('should throw an error if additionalTagsArray is empty', async () => {
+			await expect(NekosiaAPI.fetchShadowImages([])).rejects.toThrow('`additionalTags` must be a non-empty array for the shadow category');
+		});
+
+		it('should return an error response for invalid count parameter', async () => {
+			const res = await NekosiaAPI.fetchImages('catgirl', { count: 'invalid' });
+			expect(res.success).toBe(false);
+			expect(res.status).toBe(400);
+			expect(res.message).toBe('Invalid count parameter. Expected a number between 1 and 48.');
+		});
+	});
+
+	describe('fetchById', () => {
+		it('should fetch an image by ID if it exists', async () => {
+			const res = await NekosiaAPI.fetchImages('catgirl', { count: 1 });
+
+			if (res.success && res.id) {
+				const id = res.id;
+
+				const res2 = await NekosiaAPI.fetchById(id);
+				expect(res2.success).toBe(true);
+				expect(res2.status).toBe(200);
+				expect(res2).toHaveProperty('id', id);
+				expect(res2).toHaveProperty('image');
+			} else {
+				throw new Error('No images available to fetch by ID');
+			}
+		});
+
+		it('should return an error response for invalid ID format', async () => {
+			const res = await NekosiaAPI.fetchById('12345');
+			expect(res.success).toBe(false);
+			expect(res.status).toBe(400);
+			expect(res.message).toBe('The image with the provided identifier was not found.');
+		});
+	});
+
+});

package/test/integration.test.js

@@ -0,0 +1,92 @@
+const { NekosiaAPI } = require('../index.js');
+const https = require('../services/https.js');
+
+jest.mock('../services/https.js');
+
+describe('NekosiaAPI', () => {
+	beforeEach(() => {
+		https.get.mockClear();
+	});
+
+	describe('buildQueryParams', () => {
+		it('should correctly build query params', () => {
+			const options = { count: 3, additionalTags: ['tag1', 'tag2', 'tag3', 'tag4'], emptyValue: '', nullValue: null };
+			const result = NekosiaAPI.buildQueryParams(options);
+			expect(result).toBe('count=3&additionalTags=tag1,tag2,tag3,tag4');
+		});
+	});
+
+	describe('makeHttpRequest', () => {
+		it('should make a successful HTTP request', async () => {
+			const mockResponse = { data: { results: [] } };
+			https.get.mockResolvedValue(mockResponse);
+
+			const endpoint = 'https://api.nekosia.cat/test-endpoint';
+			const res = await NekosiaAPI.makeHttpRequest(endpoint);
+
+			expect(res).toEqual(mockResponse);
+			expect(https.get).toHaveBeenCalledWith(endpoint);
+		});
+
+		it('should handle HTTP request errors', async () => {
+			const mockError = new Error('Request failed');
+			https.get.mockRejectedValue(mockError);
+
+			const endpoint = 'https://api.nekosia.cat/test-endpoint';
+
+			const consoleErrorSpy = jest.spyOn(console, 'error').mockImplementation(() => {});
+
+			await expect(NekosiaAPI.makeHttpRequest(endpoint)).rejects.toThrow('Request failed');
+			expect(https.get).toHaveBeenCalledWith(endpoint);
+
+			consoleErrorSpy.mockRestore();
+		});
+	});
+
+	describe('fetchImages', () => {
+		it('should build correct endpoint and make request for given category', async () => {
+			const mockResponse = { data: { results: [] } };
+			https.get.mockResolvedValue(mockResponse);
+
+			const expectedEndpoint = 'https://api.nekosia.cat/api/v1/images/catgirl?count=2&additionalTags=cute';
+			const res = await NekosiaAPI.fetchImages('catgirl', { count: 2, additionalTags: 'cute' });
+
+			expect(res).toEqual(mockResponse);
+			expect(https.get).toHaveBeenCalledWith(expectedEndpoint);
+		});
+	});
+
+	describe('fetchShadowImages', () => {
+		it('should throw an error if additionalTags is empty', async () => {
+			await expect(NekosiaAPI.fetchShadowImages({})).rejects.toThrow('`additionalTags` must be a non-empty array for the shadow category');
+		});
+
+		it('should correctly call fetchImages with additionalTags', async () => {
+			const mockResponse = { data: { results: [] } };
+			https.get.mockResolvedValue(mockResponse);
+
+			const expectedEndpoint = 'https://api.nekosia.cat/api/v1/images/shadow?count=1&additionalTags=dark,shadow';
+			const res = await NekosiaAPI.fetchShadowImages({ count: 1, additionalTags: ['dark', 'shadow'] });
+
+			expect(res).toEqual(mockResponse);
+			expect(https.get).toHaveBeenCalledWith(expectedEndpoint);
+		});
+	});
+
+	describe('fetchById', () => {
+		it('should throw an error if id is not provided', async () => {
+			await expect(NekosiaAPI.fetchById()).rejects.toThrow('`id` parameter is required');
+		});
+
+		it('should correctly fetch image by ID', async () => {
+			const mockResponse = { data: { id: '123' } };
+			https.get.mockResolvedValue(mockResponse);
+
+			const id = '123';
+			const res = await NekosiaAPI.fetchById(id);
+
+			expect(res).toEqual(mockResponse);
+			expect(https.get).toHaveBeenCalledWith(`https://api.nekosia.cat/api/v1/getImageById/${id}`);
+		});
+	});
+});