{"id":25228884,"url":"https://github.com/rheyhannh/iloveimg-nodejs","last_synced_at":"2026-02-27T01:01:24.525Z","repository":{"id":276599756,"uuid":"929488157","full_name":"rheyhannh/iloveimg-nodejs","owner":"rheyhannh","description":"Node.js library for interacting with iLoveIMG API⚡","archived":false,"fork":false,"pushed_at":"2025-02-25T06:43:36.000Z","size":261,"stargazers_count":1,"open_issues_count":0,"forks_count":1,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-09-17T22:50:48.295Z","etag":null,"topics":["iloveapi","iloveimg","image-processing","javascript","nodejs"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/rheyhannh.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2025-02-08T17:02:52.000Z","updated_at":"2025-02-25T06:43:40.000Z","dependencies_parsed_at":"2025-02-24T02:19:32.098Z","dependency_job_id":"2125f022-a2bb-4d19-b5fa-6ac2be5c8adb","html_url":"https://github.com/rheyhannh/iloveimg-nodejs","commit_stats":null,"previous_names":["rheyhannh/iloveimg-nodejs"],"tags_count":10,"template":false,"template_full_name":null,"purl":"pkg:github/rheyhannh/iloveimg-nodejs","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rheyhannh%2Filoveimg-nodejs","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rheyhannh%2Filoveimg-nodejs/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rheyhannh%2Filoveimg-nodejs/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rheyhannh%2Filoveimg-nodejs/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/rheyhannh","download_url":"https://codeload.github.com/rheyhannh/iloveimg-nodejs/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rheyhannh%2Filoveimg-nodejs/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29879896,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-26T23:51:21.483Z","status":"ssl_error","status_checked_at":"2026-02-26T23:50:46.793Z","response_time":89,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["iloveapi","iloveimg","image-processing","javascript","nodejs"],"created_at":"2025-02-11T10:46:11.416Z","updated_at":"2026-02-27T01:01:22.488Z","avatar_url":"https://github.com/rheyhannh.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# ILoveIMG API - Node.js Library  \n\nA Node.js library for interacting with the [ILoveIMG API](https://www.iloveapi.com/products/image-rest-api).\n\n## ⚠️ Important Before You Start  \n- This library is **not** officially developed by the ILoveIMG [team](https://github.com/ilovepdf). I created it because I needed ILoveIMG’s tools (especially for image processing) in my application, and there was no official Node.js library available. Before using this library, please **cross-check** with the [official documentation](https://www.iloveapi.com/docs/api-reference) to ensure compatibility, especially for the available options and parameters of each specific tool.\n- As of the time you're reading this, this library **does not yet** support all ILoveIMG tools. Currently, it only supports:  \n  - `convertimage`  \n  - `upscaleimage`  \n  - `watermarkimage`  \n  - `removebackgroundimage`\n- It only supports uploading or adding images from a public URL, so you need to use an image or storage provider that can serve your image publicly.\n- Some implementations in this library **may differ** from ILoveApi's official library behavior.\n- You may need to read and understand how their API [request workflows](https://www.iloveapi.com/docs/api-reference#request-workflow) works first.\n- I do **not** have a fixed timeline for updates, so contributions via pull requests (PRs) are highly welcome🚀\n\n## 📌 When Should You Use This Library?  \nUse this library if:  \n- You need to integrate ILoveApi’s image services into a **Node.js** application.  \n- Your project follows **ES Module (ESM)** syntax (`import`), not CommonJS (`require`).\n- You want **strong type definitions** and **clear documentation** in your code editor to simplify development.  \n\n## 📖 Introduction  \nThis library is built using **[Axios](https://axios-http.com/)**, **[jsonwebtoken](https://www.npmjs.com/package/jsonwebtoken)**, and **[Zod](https://zod.dev/)**, along with some development dependencies for testing.  \n- **Axios** handles communication with the ILoveIMG API.  \n- **jsonwebtoken** is used to generate the **[self-signed](https://www.iloveapi.com/docs/api-reference#authentication) authentication token** required for each API request ([start](https://www.iloveapi.com/docs/api-reference#start), [upload](https://www.iloveapi.com/docs/api-reference#upload), [process](https://www.iloveapi.com/docs/api-reference#process), [download](https://www.iloveapi.com/docs/api-reference#download), etc.).\n- **Zod** is used as a schema validator for request options and parameters since this library is built in JavaScript, not TypeScript.\n  - This means if you provide invalid options, you will likely receive a **[ZodError](https://zod.dev/ERROR_HANDLING?id=zoderror)**, helping you catch mistakes early before initiating requests.\n\nBy using this library, you get a more structured and type-safe way to interact with ILoveIMG’s API ✨\n\n## 📋 Requirements\n\nTo use this library, ensure you have the following installed:\n\n1. **NPM** - Package built with version `@10.9.0`.  \n2. **Node.js** - Package built with version `@22.12.0`.  \n\nYou can download them here:  \n- [Download NPM](https://www.npmjs.com/)  \n- [Download Node.js](https://nodejs.org/)\n\n## ⚙️ Installation\nYou can install the library via [NPM](https://www.npmjs.com/). Run the following command:\n```sh\nnpm install @rheyhannh/iloveimg-nodejs\n```\n\n## 👋 Getting Started\n### Using `then/catch` syntax\n```js\nimport ILoveIMGApi from '@rheyhannh/iloveimg-nodejs';\n\nconst iloveimg = new ILoveIMGApi('publicKey', 'secretKey');\nconst task = iloveimg.newTask('convertimage');\n\ntask.start()\n  .then(({ task_id, server, remaining_files }) =\u003e {\n      return task.addFile({ cloud_file: 'https://i.imgur.com/awesome.jpeg', filename: 'awesome.jpeg' });\n  })\n  .then(({ server_filename }) =\u003e {\n      return task.process();\n  })\n  .then(({ download_filename, filesize, output_filesize, output_filenumber, output_extensions, timer, status }) =\u003e {\n      return task.download(); // AxiosResponse\n  });\n```\n\n### Using `async/await` syntax\n```js\nimport ILoveIMGApi from '@rheyhannh/iloveimg-nodejs';\n\nconst iloveimg = new ILoveIMGApi('publicKey', 'secretKey');\nconst task = iloveimg.newTask('convertimage');\n\nawait task.start();\nawait task.addFile({ cloud_file: 'https://i.imgur.com/awesome.jpeg', filename: 'awesome.jpeg' });\nawait task.process();\n\nconst result = await task.download(); // AxiosResponse\n```\n\n### List project tasks\n```js\nimport ILoveIMGApi from '@rheyhannh/iloveimg-nodejs';\n\n// Project secretKey required otherwise listTasks() will throw an Error.\nconst iloveimg = new ILoveIMGApi('publicKey', 'secretKey');\n\n// See available optional parameters https://www.iloveapi.com/docs/api-reference#task\nconst tasks = await iloveimg.listTasks({});\n\n// See https://www.iloveapi.com/docs/api-reference#webhooks at Task response example on data.task\nconsole.log(tasks[0]);\n```\n\n### Get current task details\n```js\nconst iloveimg = new ILoveIMGApi('publicKey', 'secretKey');\nconst task = iloveimg.newTask('convertimage');\n\n// You need to call start() first otherwise details() will throw an Error.\nawait task.start();\nconst task_details = await task.details();\n\n// false, when no uploaded files related to task\nconsole.log(task_details);\n\n// When files already uploaded or processing task\n// See https://www.iloveapi.com/docs/api-reference#task\nconsole.log(task_details);\n\n// When task finish processing\n// See https://www.iloveapi.com/docs/api-reference#webhooks at Task response example on data.task with additional `files` attribute\nconsole.log(task_details); \n```\n\n### Delete current task\n```js\nconst iloveimg = new ILoveIMGApi('publicKey', 'secretKey');\nconst task = iloveimg.newTask('convertimage');\n\n// You need to call start() first otherwise delete() will throw an Error.\nawait task.start();\nawait task.delete();\n```\n\n### Get current task tool\n```js\nconst iloveimg = new ILoveIMGApi('publicKey', 'secretKey');\nconst task = iloveimg.newTask('convertimage');\nconsole.log(task.getTool()); // 'convertimage'\n```\n\n### Get current task id\n```js\nconst iloveimg = new ILoveIMGApi('publicKey', 'secretKey');\nconst task = iloveimg.newTask('upscaleimage');\n\n// You need to call start() first otherwise it will return undefined.\nawait task.start();\nconsole.log(task.getTaskId()); // ex:'taskid'\n```\n\n### Get current task uploaded files\n```js\nconst iloveimg = new ILoveIMGApi('publicKey', 'secretKey');\nconst task = iloveimg.newTask('upscaleimage');\n\n// You need to call start() and add some files first otherwise it will return undefined.\nawait task.start();\nawait task.addFile({ cloud_file: 'https://i.imgur.com/awesome.jpeg', filename: 'awesome.jpeg' });\n\nconst files = task.getUploadedFiles(); // An array containing uploaded files\nconsole.log(files[0].server_filename) // ex:'thispropassignedbyiloveimgserver.jpeg'\nconsole.log(files[0].filename) // 'awesome.jpeg'\n```\n\n### Get your project remaining files\n```js\nconst iloveimg = new ILoveIMGApi('publicKey', 'secretKey');\nconst task = iloveimg.newTask('upscaleimage');\n\n// You need to call start() first otherwise it will return undefined.\nawait task.start();\nconsole.log(task.getRemainingFiles()); // ex:2320\n```\n\n### Delete current task files\n```js\nconst iloveimg = new ILoveIMGApi('publicKey', 'secretKey');\nconst task = iloveimg.newTask('upscaleimage');\n\nawait task.start();\nawait task.addFile({ cloud_file: 'https://i.imgur.com/awesome.jpeg', filename: 'awesome.jpeg' });\n\nconst files = task.getUploadedFiles();\nconsole.log(files[0].server_filename) // ex:'xyz.jpeg'\n\nawait task.deleteFile({ server_filename: 'xyz.jpeg' })\n```\n\n## \u003c/\u003e Implementation\n\n### Simplified Request Parameter Handling\n\nDuring development, structuring request parameters correctly can sometimes be challenging. This library provides method parameters that you can use with specific APIs and tool options in the `process()` API.\nAdditionally, it includes `Zod` validation, which ensures that required attributes are present and correctly typed before sending a request. If any parameters are missing or incorrectly formatted, a `ZodError` is thrown—helping you catch issues early and avoid unnecessary failed requests to the server.\n\n**Example: Using Generic and Tool-Specific Options in `process()`**\n```js\nconst iloveimg = new ILoveIMGApi('publicKey', 'secretKey');\nconst task = iloveimg.newTask('upscaleimage');\n\nawait task.start();\n\n// Generic options: These are optional parameters that apply to the `process()` API.\n// The library automatically handles required attributes like `task`, `tool`, and `files`, \n// so you only need to provide the optional ones based on your needs.\n// Note: Some PDF-related attributes are excluded because this library focuses on IMG processing.\n// Reference: https://www.iloveapi.com/docs/api-reference#process\nconst options = {\n    try_image_repair: false,\n    custom_string: 'some-value',\n};\n\n// Tool-specific options: These are parameters for specific tools. \n// In the ILoveIMG documentation, these are referred to as 'extra parameters'.\n// Some attributes are required, and if they are missing or incorrectly typed, a ZodError will be thrown.\n// Reference: https://www.iloveapi.com/docs/api-reference#upscaleimage-extra-parameters\nconst upscaleOptions = {\n    multiplier: 4\n};\n\nawait task.addFile({ cloud_file: 'https://i.imgur.com/awesome.jpeg', filename: 'awesome.jpeg' });\nawait task.process(options, upscaleOptions);\n```\n\n**Example: Debugging API Requests**\n\nILoveApi's provides a [debug](https://www.iloveapi.com/docs/api-reference#testing) mode that allows you to inspect each request sent to their servers. This is particularly useful for testing and understanding what data is being transmitted, such as request bodies, parameters, and other values.\n\n**Important**\n- When using debug mode, the API does not actually process your request.\n- The response will contain details about your request instead of performing the intended action.\n- Debugging does not consume your project’s file usage quota.\n- You don’t need to call `start()` before debugging other API methods.\n\n```js\nconst iloveimg = new ILoveIMGApi('publicKey', 'secretKey');\nconst task = iloveimg.newTask('upscaleimage');\n\n// Debugging `start()` API\nawait task.start({ debug: true });\n\n// Debugging `addFile()` API\nawait task.addFile({ debug: true });\n\n// Debugging `deleteFile()` API\nawait task.deleteFile({ debug: true });\n\n// Debugging `process()` API\nawait task.process({ debug: true });\n\n// Debugging `download()` API\nawait task.download({ debug: true });\n```\n\n### Making Requests for a Specific Task\nEach task initialized with `start()` provides a `getServer()` method, which returns an [AxiosInstance](https://axios-http.com/docs/instance). This instance is pre-configured with the required authentication token and points to the correct ILoveIMG API server. This is useful when you need to send direct requests to the server without using the built-in methods.\n\n**Example: Deleting a Task Without `delete()`**\n```js\nconst iloveimg = new ILoveIMGApi('publicKey', 'secretKey');\nconst task = iloveimg.newTask('upscaleimage');\n\n// Start the task first; otherwise, getServer() will return undefined.\nawait task.start();\n\nconst taskId = task.getTaskId(); // Get the task ID\nconst axios = task.getServer(); // Get the Axios instance\n\nconst endpoint = `task/${taskId}`;\nawait axios.delete(endpoint);\n```\n\nAfter calling `start()`, let's assume the task ID are `loremipsumdolor` and is assigned to the server `api8g.iloveimg.com`. The above implementation essentially sends the following request:\n\n```http\nDELETE https://api8g.iloveimg.com/v1/task/loremipsumdolor\n```\n\n### Task Module\nWhen your application implements a [webhook](https://www.iloveapi.com/docs/api-reference#webhooks), ILoveApi's servers will notify your webhook once a task has been processed. In such cases, you may need to download the processed file or retrieve task details for a specific task ID and its assigned server. To streamline this process, you can use the `Task` module, which provides functionality to download processed files and fetch task details effortlessly.\n\n**Example: Downloading a Processed File for a Specific Task ID and Server**\n```js\nimport { Task } from '@rheyhannh/iloveimg-nodejs';\n\nconst task = new Task('publicKey', 'secretKey', 'taskId', 'taskServer');\n\nconst result = await task.download(); // AxiosResponse\n```\n\n**Example: Retrieve Task Details for a Specific Task ID and Server**\n```js\nimport { Task } from '@rheyhannh/iloveimg-nodejs';\n\nconst task = new Task('publicKey', 'secretKey', 'taskId', 'taskServer');\n\nconst details = await task.details();\n```\n\n### Auth Module\nIf you prefer to use a custom HTTP client like [Got](https://www.npmjs.com/package/got), [Needle](https://www.npmjs.com/package/needle), or another library instead of our built-in Axios-based method, you'll need a way to handle authentication separately. The `Auth` module helps manage authentication by issuing, verifying, and refreshing tokens required for requests to the `ILoveApi` servers.\n\n**Example: Using Auth Module**\n```js\nimport { Auth } from '@rheyhannh/iloveimg-nodejs';\n\nconst auth = new Auth('publicKey', 'secretKey');\n\nconst token = await auth.getToken(); // JWT\nconst payload = auth.verifyToken(); // JWT Payload\n\n// Use the token when making requests to the `ILoveApi` server.\n// Include it in the `Authorization` header with the 'Bearer' prefix.\n```\n\n**Example: Customizing a Self-Signed Token Payload**\n\nWhen you provide a `secretKey`, authentication with the server uses a self-signed token. This allows you to customize the token's payload, including:\n- `iss` – The token issuer (e.g., your domain)\n- `age` – The token's validity period in seconds\n\nYou can define these options when creating an authentication instance, as shown below:\n```js\nimport ILoveIMGApi, { Auth, Task } from '@rheyhannh/iloveimg-nodejs';\n\nconst auth = new Auth('publicKey', 'secretKey', {\n  iss: 'mydomain.com', // Custom issuer\n  age: 1800 // Token valid for 30 minutes\n});\n\nconst token = await auth.getToken(); // Returns JWT token\nconst payload = auth.verifyToken(); // Returns decoded JWT payload\n\n// You can also customize token settings when using `ILoveIMGApi` or `Task` instances\nconst iloveimg = new ILoveIMGApi('publicKey', 'secretKey', {\n  iss: 'mydomain.com',\n  age: 7200 // Token valid for 2 hours\n});\n\nconst task = new Task('publicKey', 'secretKey', 'taskId', 'taskServer', {\n  iss: 'mydomain.com',\n  age: 3600 // Token valid for 1 hour\n});\n```\nThis flexibility allows you to define different token settings depending on your use case 🤹🏻‍♀️\n\n## 🔮 Whats Next\nHere are some next steps you might find useful:\n- 📖 **Explore the API Documentation** - Check out the official [ILoveAPI](https://www.iloveapi.com/docs/api-reference) or [ILoveIMG](https://www.iloveapi.com/docs/image-guides) documentation to learn more about the available features.\n- 🔧 **Contribute to the Project** – Found a bug or have a feature request? Feel free to open an [issue](https://github.com/rheyhannh/iloveimg-nodejs/issues) or submit a [pull request](https://github.com/rheyhannh/iloveimg-nodejs/pulls). \n- 💬 **Join the Discussion** – Have questions or want to share your experience? Start a [discussion](https://github.com/rheyhannh/iloveimg-nodejs/discussions).\n- 🌟 **Give it a Star** – If this library has been helpful for your project, consider giving it a ⭐ to show your support!\n\nHappy coding! 🎉\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frheyhannh%2Filoveimg-nodejs","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frheyhannh%2Filoveimg-nodejs","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frheyhannh%2Filoveimg-nodejs/lists"}