@nghiavuive/random-image 1.1.0 → 1.2.0

package/README.md

@@ -1,6 +1,6 @@
 # random-image
 
-A generic utility library to fetch random images from various providers like Unsplash and Pexels, with built-in download capabilities.
+A generic utility library to fetch random images from various providers like Unsplash and Pexels, with built-in download capabilities and CLI support.
 
 ## Installation
 
@@ -8,7 +8,99 @@ A generic utility library to fetch random images from various providers like Uns
 npm install @nghiavuive/random-image
 ```
 
-## Usage
+## CLI Usage
+
+You can use the CLI without installation via `npx`:
+
+```bash
+npx @nghiavuive/random-image fetch --query "nature" --download
+```
+
+Or install globally:
+
+```bash
+npm install -g @nghiavuive/random-image
+random-image fetch --query "mountains" --download
+```
+
+### CLI Setup
+
+Set environment variables for the providers you want to use:
+
+```bash
+export UNSPLASH_KEY="your_unsplash_access_key"
+export PEXELS_KEY="your_pexels_api_key"
+export PIXABAY_KEY="your_pixabay_api_key"
+```
+
+Or create a `.env` file in your project:
+
+```env
+UNSPLASH_KEY=your_unsplash_access_key
+PEXELS_KEY=your_pexels_api_key
+PIXABAY_KEY=your_pixabay_api_key
+```
+
+### CLI Commands
+
+#### Fetch Command
+
+```bash
+# Basic usage - uses random provider from available API keys
+random-image fetch
+
+# Fetch with search query
+random-image fetch --query "nature"
+
+# Fetch and download
+random-image fetch --query "mountains" --download
+
+# Specify provider
+random-image fetch --provider unsplash --query "ocean"
+
+# Custom dimensions
+random-image fetch --width 1920 --height 1080 --query "sunset"
+
+# Download to custom directory
+random-image fetch --query "cats" --download ./my-images
+
+# Download with custom filename
+random-image fetch --query "dogs" --download --filename "my-dog.jpg"
+
+# Download with overwrite
+random-image fetch --download --overwrite
+
+# Generate random UUID filename
+random-image fetch --download --no-keep-original-name
+
+# Full example with all options
+random-image fetch \
+  --provider pexels \
+  --query "abstract art" \
+  --width 2560 \
+  --height 1440 \
+  --orientation landscape \
+  --download ./wallpapers \
+  --filename "wallpaper.jpg" \
+  --overwrite
+```
+
+#### CLI Flags
+
+- `-q, --query <search>`: Search query for the image
+- `-w, --width <number>`: Width of the image
+- `-h, --height <number>`: Height of the image
+- `--quality <number>`: Quality of the image (0-100)
+- `--orientation <type>`: Image orientation (`landscape` or `portrait`)
+- `-p, --provider <name>`: Provider to use (`unsplash`, `pexels`, `pixabay`, or `random`)
+- `-d, --download [path]`: Download the image (default: `./downloads`)
+- `--filename <name>`: Custom filename for downloaded image
+- `--overwrite`: Overwrite existing files
+- `--no-keep-original-name`: Generate random UUID filename instead of keeping original
+
+**Random Provider Mode**: If you don't specify `--provider` or use `--provider random`, the CLI will randomly select from providers that have API keys configured. This is useful for distributing requests across multiple services.
+
+## Programmatic Usage
 
 You need to obtain API keys from the respective providers:
 - [Unsplash Developers](https://unsplash.com/developers)
@@ -149,8 +241,16 @@ Result object containing image information:
 
 ## Features
 
+### CLI Features
+- ✅ Command-line interface for quick image fetching
+- ✅ Random provider selection when multiple API keys are available
+- ✅ Environment variable support for API keys
+- ✅ Direct download from command line
+- ✅ All library features available via CLI flags
+
+### Library Features
+
 ### Download Functionality
-- ✅ Automatic directory creation
 - ✅ Flexible filename options:
   - Custom filename
   - Keep original filename from URL (default)

package/dist/cli.js

@@ -0,0 +1,346 @@
+#!/usr/bin/env node
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+
+// src/cli.ts
+var import_commander = require("commander");
+
+// src/providers/unsplash.ts
+var import_axios = __toESM(require("axios"));
+var UnsplashProvider = class {
+  constructor(accessKey) {
+    this.accessKey = accessKey;
+  }
+  async fetchRandomImage(options) {
+    const response = await import_axios.default.get("https://api.unsplash.com/photos/random", {
+      headers: {
+        Authorization: `Client-ID ${this.accessKey}`
+      },
+      params: {
+        query: options.query,
+        orientation: options.orientation
+      }
+    });
+    const data = response.data;
+    const photo = Array.isArray(data) ? data[0] : data;
+    const baseUrl = photo.urls.raw;
+    const sizeParams = new URLSearchParams();
+    if (options.height || options.width) {
+      sizeParams.append("fit", "crop");
+      sizeParams.append("crop", "entropy");
+    }
+    if (options.width) sizeParams.append("w", options.width.toString());
+    if (options.height) sizeParams.append("h", options.height.toString());
+    if (options.quality) sizeParams.append("q", options.quality.toString());
+    const finalUrl = `${baseUrl}&${sizeParams.toString()}`;
+    return {
+      url: finalUrl,
+      width: options.width || photo.width,
+      height: options.height || photo.height,
+      author: photo.user.name,
+      authorUrl: photo.user.links.html,
+      originalUrl: photo.links.html
+      // Link to photo page
+    };
+  }
+};
+
+// src/providers/pexels.ts
+var import_axios2 = __toESM(require("axios"));
+var PexelsProvider = class {
+  constructor(apiKey) {
+    this.apiKey = apiKey;
+  }
+  async fetchRandomImage(options) {
+    const endpoint = options.query ? "https://api.pexels.com/v1/search" : "https://api.pexels.com/v1/curated";
+    const randomPage = Math.floor(Math.random() * 100) + 1;
+    const params = {
+      per_page: 1,
+      page: randomPage
+    };
+    if (options.query) params.query = options.query;
+    const response = await import_axios2.default.get(endpoint, {
+      headers: {
+        Authorization: this.apiKey
+      },
+      params
+    });
+    const data = response.data;
+    if (!data.photos || data.photos.length === 0) {
+      throw new Error("No images found on Pexels");
+    }
+    const photo = data.photos[0];
+    const baseUrl = photo.src.original;
+    const sizeParams = new URLSearchParams();
+    sizeParams.append("auto", "compress");
+    sizeParams.append("cs", "tinysrgb");
+    if (options.width) sizeParams.append("w", options.width.toString());
+    if (options.height) sizeParams.append("h", options.height.toString());
+    const finalUrl = `${baseUrl}?${sizeParams.toString()}`;
+    return {
+      url: finalUrl,
+      width: options.width || photo.width,
+      height: options.height || photo.height,
+      author: photo.photographer,
+      authorUrl: photo.photographer_url,
+      originalUrl: photo.url
+    };
+  }
+};
+
+// src/providers/pixabay.ts
+var import_axios3 = __toESM(require("axios"));
+var PixabayProvider = class {
+  constructor(apiKey) {
+    this.apiKey = apiKey;
+  }
+  async fetchRandomImage(options) {
+    const params = {
+      key: this.apiKey,
+      q: options.query || "",
+      per_page: 20
+      // Fetch a few to pick randomly
+    };
+    if (options.orientation) {
+      params.orientation = options.orientation === "portrait" ? "vertical" : "horizontal";
+    }
+    const response = await import_axios3.default.get("https://pixabay.com/api/", {
+      params
+    });
+    const hits = response.data.hits;
+    if (!hits || hits.length === 0) {
+      throw new Error("No images found");
+    }
+    const randomHit = hits[Math.floor(Math.random() * hits.length)];
+    return {
+      url: randomHit.largeImageURL || randomHit.webformatURL,
+      width: randomHit.imageWidth || randomHit.webformatWidth,
+      height: randomHit.imageHeight || randomHit.webformatHeight,
+      author: randomHit.user,
+      authorUrl: `https://pixabay.com/users/${randomHit.user}-${randomHit.user_id}/`,
+      originalUrl: randomHit.pageURL
+    };
+  }
+};
+
+// src/image-fetcher.ts
+var fs = __toESM(require("fs"));
+var path = __toESM(require("path"));
+var import_axios4 = __toESM(require("axios"));
+var import_uuid = require("uuid");
+var RandomImage = class {
+  constructor(provider) {
+    this.provider = provider;
+  }
+  /**
+   * Fetches a random image based on the provided options.
+   * @param options - Configuration options for the image (width, height, query, etc.)
+   * @returns A promise that resolves to an ImageResult object.
+   */
+  async getRandom(options = {}) {
+    return this.provider.fetchRandomImage(options);
+  }
+  /**
+   * Downloads an image to a specified directory.
+   * @param imageUrl - The URL of the image to download (can be a string or ImageResult object)
+   * @param destinationPath - The directory path where the image will be saved
+   * @param options - Download options (filename, overwrite, etc.)
+   * @returns A promise that resolves to the full path of the downloaded file
+   */
+  async download(imageUrl, destinationPath, options = {}) {
+    const url = typeof imageUrl === "string" ? imageUrl : imageUrl.url;
+    if (!fs.existsSync(destinationPath)) {
+      fs.mkdirSync(destinationPath, { recursive: true });
+    }
+    let finalFilename;
+    if (options.filename) {
+      finalFilename = options.filename;
+    } else if (options.keepOriginalName) {
+      const urlPath = new URL(url).pathname;
+      const urlFilename = path.basename(urlPath);
+      if (urlFilename && urlFilename.length > 0 && urlFilename !== "/") {
+        finalFilename = urlFilename;
+      } else {
+        const ext = this.getExtensionFromUrl(url) || ".jpg";
+        finalFilename = `${(0, import_uuid.v7)()}${ext}`;
+      }
+    } else {
+      const ext = this.getExtensionFromUrl(url) || ".jpg";
+      finalFilename = `${(0, import_uuid.v7)()}${ext}`;
+    }
+    if (!path.extname(finalFilename)) {
+      finalFilename += ".jpg";
+    }
+    const fullPath = path.join(destinationPath, finalFilename);
+    if (fs.existsSync(fullPath) && !options.overwrite) {
+      throw new Error(`File already exists: ${fullPath}. Set overwrite: true to replace it.`);
+    }
+    try {
+      const response = await import_axios4.default.get(url, {
+        responseType: "stream",
+        maxRedirects: 5
+        // Automatically handle redirects
+      });
+      const writer = fs.createWriteStream(fullPath);
+      response.data.pipe(writer);
+      return new Promise((resolve2, reject) => {
+        writer.on("finish", () => {
+          resolve2(fullPath);
+        });
+        writer.on("error", (err) => {
+          fs.unlink(fullPath, () => {
+          });
+          reject(err);
+        });
+        response.data.on("error", (err) => {
+          writer.close();
+          fs.unlink(fullPath, () => {
+          });
+          reject(err);
+        });
+      });
+    } catch (error) {
+      if (import_axios4.default.isAxiosError(error)) {
+        throw new Error(`Failed to download image: ${error.message}`);
+      }
+      throw error;
+    }
+  }
+  /**
+   * Helper method to extract file extension from URL
+   * @param url - The URL to extract extension from
+   * @returns The file extension (e.g., '.jpg', '.png') or null
+   */
+  getExtensionFromUrl(url) {
+    try {
+      const urlPath = new URL(url).pathname;
+      const ext = path.extname(urlPath);
+      return ext || null;
+    } catch {
+      return null;
+    }
+  }
+};
+
+// src/cli.ts
+var path2 = __toESM(require("path"));
+var dotenv = __toESM(require("dotenv"));
+var fs2 = __toESM(require("fs"));
+var possibleEnvPaths = [
+  path2.resolve(process.cwd(), ".env"),
+  // Current working directory
+  path2.resolve(__dirname, ".env"),
+  // Same directory as the CLI script (dist/)
+  path2.resolve(__dirname, "..", ".env")
+  // Parent directory (root of project)
+];
+for (const envPath of possibleEnvPaths) {
+  if (fs2.existsSync(envPath)) {
+    dotenv.config({ path: envPath });
+    console.log(`Loaded environment from: ${envPath}`);
+    break;
+  }
+}
+var program = new import_commander.Command();
+program.name("random-image").description("CLI tool to fetch random images from various providers").version("1.2.0");
+program.command("fetch").description("Fetch a random image from image providers").option("-q, --query <search>", "Search query for the image").option("-w, --width <number>", "Width of the image", parseInt).option("-h, --height <number>", "Height of the image", parseInt).option("--quality <number>", "Quality of the image (0-100)", parseInt).option("--orientation <type>", "Image orientation (landscape or portrait)").option("-p, --provider <name>", "Provider to use (unsplash, pexels, pixabay, or random)", "random").option("-d, --download [path]", "Download the image to specified directory (default: ./downloads)").option("--filename <name>", "Custom filename for downloaded image").option("--overwrite", "Overwrite existing files", false).option("--no-keep-original-name", "Generate random UUID filename instead of keeping original").action(async (options) => {
+  try {
+    const providers = {
+      unsplash: process.env.UNSPLASH_KEY,
+      pexels: process.env.PEXELS_KEY,
+      pixabay: process.env.PIXABAY_KEY
+    };
+    let providerName = options.provider.toLowerCase();
+    if (providerName === "random") {
+      const availableProviders = Object.entries(providers).filter(([_, key]) => key).map(([name]) => name);
+      if (availableProviders.length === 0) {
+        console.error("Error: No API keys found in environment variables.");
+        console.error("Please set at least one of: UNSPLASH_KEY, PEXELS_KEY, PIXABAY_KEY");
+        process.exit(1);
+      }
+      providerName = availableProviders[Math.floor(Math.random() * availableProviders.length)];
+      console.log(`Using random provider: ${providerName}`);
+    }
+    let provider;
+    const apiKey = providers[providerName];
+    if (!apiKey) {
+      console.error(`Error: API key for ${providerName} not found.`);
+      console.error(`Please set ${providerName.toUpperCase()}_KEY environment variable.`);
+      process.exit(1);
+    }
+    switch (providerName) {
+      case "unsplash":
+        provider = new UnsplashProvider(apiKey);
+        break;
+      case "pexels":
+        provider = new PexelsProvider(apiKey);
+        break;
+      case "pixabay":
+        provider = new PixabayProvider(apiKey);
+        break;
+      default:
+        console.error(`Error: Unknown provider "${providerName}"`);
+        console.error("Available providers: unsplash, pexels, pixabay, random");
+        process.exit(1);
+    }
+    const fetcher = new RandomImage(provider);
+    const fetchOptions = {};
+    if (options.query) fetchOptions.query = options.query;
+    if (options.width) fetchOptions.width = options.width;
+    if (options.height) fetchOptions.height = options.height;
+    if (options.quality) fetchOptions.quality = options.quality;
+    if (options.orientation) fetchOptions.orientation = options.orientation;
+    console.log("Fetching random image...");
+    const image = await fetcher.getRandom(fetchOptions);
+    console.log("\n\u2713 Image fetched successfully!");
+    console.log(`  URL: ${image.url}`);
+    console.log(`  Size: ${image.width}x${image.height}`);
+    console.log(`  Author: ${image.author}`);
+    if (image.authorUrl) console.log(`  Author URL: ${image.authorUrl}`);
+    console.log(`  Original: ${image.originalUrl}`);
+    if (options.download !== void 0) {
+      const downloadPath = typeof options.download === "string" ? options.download : "./downloads";
+      console.log(`
+Downloading to ${path2.resolve(downloadPath)}...`);
+      const downloadOptions = {
+        overwrite: options.overwrite,
+        keepOriginalName: options.keepOriginalName
+      };
+      if (options.filename) {
+        downloadOptions.filename = options.filename;
+      }
+      const filePath = await fetcher.download(image, downloadPath, downloadOptions);
+      console.log(`\u2713 Downloaded: ${filePath}`);
+    }
+  } catch (error) {
+    if (error instanceof Error) {
+      console.error(`
+Error: ${error.message}`);
+    } else {
+      console.error("\nAn unexpected error occurred");
+    }
+    process.exit(1);
+  }
+});
+program.parse(process.argv);

package/dist/cli.mjs

@@ -0,0 +1,377 @@
+#!/usr/bin/env node
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __esm = (fn, res) => function __init() {
+  return fn && (res = (0, fn[__getOwnPropNames(fn)[0]])(fn = 0)), res;
+};
+var __commonJS = (cb, mod) => function __require() {
+  return mod || (0, cb[__getOwnPropNames(cb)[0]])((mod = { exports: {} }).exports, mod), mod.exports;
+};
+
+// src/types.ts
+var init_types = __esm({
+  "src/types.ts"() {
+    "use strict";
+  }
+});
+
+// src/providers/unsplash.ts
+import axios from "axios";
+var UnsplashProvider;
+var init_unsplash = __esm({
+  "src/providers/unsplash.ts"() {
+    "use strict";
+    UnsplashProvider = class {
+      constructor(accessKey) {
+        this.accessKey = accessKey;
+      }
+      async fetchRandomImage(options) {
+        const response = await axios.get("https://api.unsplash.com/photos/random", {
+          headers: {
+            Authorization: `Client-ID ${this.accessKey}`
+          },
+          params: {
+            query: options.query,
+            orientation: options.orientation
+          }
+        });
+        const data = response.data;
+        const photo = Array.isArray(data) ? data[0] : data;
+        const baseUrl = photo.urls.raw;
+        const sizeParams = new URLSearchParams();
+        if (options.height || options.width) {
+          sizeParams.append("fit", "crop");
+          sizeParams.append("crop", "entropy");
+        }
+        if (options.width) sizeParams.append("w", options.width.toString());
+        if (options.height) sizeParams.append("h", options.height.toString());
+        if (options.quality) sizeParams.append("q", options.quality.toString());
+        const finalUrl = `${baseUrl}&${sizeParams.toString()}`;
+        return {
+          url: finalUrl,
+          width: options.width || photo.width,
+          height: options.height || photo.height,
+          author: photo.user.name,
+          authorUrl: photo.user.links.html,
+          originalUrl: photo.links.html
+          // Link to photo page
+        };
+      }
+    };
+  }
+});
+
+// src/providers/pexels.ts
+import axios2 from "axios";
+var PexelsProvider;
+var init_pexels = __esm({
+  "src/providers/pexels.ts"() {
+    "use strict";
+    PexelsProvider = class {
+      constructor(apiKey) {
+        this.apiKey = apiKey;
+      }
+      async fetchRandomImage(options) {
+        const endpoint = options.query ? "https://api.pexels.com/v1/search" : "https://api.pexels.com/v1/curated";
+        const randomPage = Math.floor(Math.random() * 100) + 1;
+        const params = {
+          per_page: 1,
+          page: randomPage
+        };
+        if (options.query) params.query = options.query;
+        const response = await axios2.get(endpoint, {
+          headers: {
+            Authorization: this.apiKey
+          },
+          params
+        });
+        const data = response.data;
+        if (!data.photos || data.photos.length === 0) {
+          throw new Error("No images found on Pexels");
+        }
+        const photo = data.photos[0];
+        const baseUrl = photo.src.original;
+        const sizeParams = new URLSearchParams();
+        sizeParams.append("auto", "compress");
+        sizeParams.append("cs", "tinysrgb");
+        if (options.width) sizeParams.append("w", options.width.toString());
+        if (options.height) sizeParams.append("h", options.height.toString());
+        const finalUrl = `${baseUrl}?${sizeParams.toString()}`;
+        return {
+          url: finalUrl,
+          width: options.width || photo.width,
+          height: options.height || photo.height,
+          author: photo.photographer,
+          authorUrl: photo.photographer_url,
+          originalUrl: photo.url
+        };
+      }
+    };
+  }
+});
+
+// src/providers/pixabay.ts
+import axios3 from "axios";
+var PixabayProvider;
+var init_pixabay = __esm({
+  "src/providers/pixabay.ts"() {
+    "use strict";
+    PixabayProvider = class {
+      constructor(apiKey) {
+        this.apiKey = apiKey;
+      }
+      async fetchRandomImage(options) {
+        const params = {
+          key: this.apiKey,
+          q: options.query || "",
+          per_page: 20
+          // Fetch a few to pick randomly
+        };
+        if (options.orientation) {
+          params.orientation = options.orientation === "portrait" ? "vertical" : "horizontal";
+        }
+        const response = await axios3.get("https://pixabay.com/api/", {
+          params
+        });
+        const hits = response.data.hits;
+        if (!hits || hits.length === 0) {
+          throw new Error("No images found");
+        }
+        const randomHit = hits[Math.floor(Math.random() * hits.length)];
+        return {
+          url: randomHit.largeImageURL || randomHit.webformatURL,
+          width: randomHit.imageWidth || randomHit.webformatWidth,
+          height: randomHit.imageHeight || randomHit.webformatHeight,
+          author: randomHit.user,
+          authorUrl: `https://pixabay.com/users/${randomHit.user}-${randomHit.user_id}/`,
+          originalUrl: randomHit.pageURL
+        };
+      }
+    };
+  }
+});
+
+// src/image-fetcher.ts
+import * as fs from "fs";
+import * as path from "path";
+import axios4 from "axios";
+import { v7 as uuidv4 } from "uuid";
+var RandomImage;
+var init_image_fetcher = __esm({
+  "src/image-fetcher.ts"() {
+    "use strict";
+    RandomImage = class {
+      constructor(provider) {
+        this.provider = provider;
+      }
+      /**
+       * Fetches a random image based on the provided options.
+       * @param options - Configuration options for the image (width, height, query, etc.)
+       * @returns A promise that resolves to an ImageResult object.
+       */
+      async getRandom(options = {}) {
+        return this.provider.fetchRandomImage(options);
+      }
+      /**
+       * Downloads an image to a specified directory.
+       * @param imageUrl - The URL of the image to download (can be a string or ImageResult object)
+       * @param destinationPath - The directory path where the image will be saved
+       * @param options - Download options (filename, overwrite, etc.)
+       * @returns A promise that resolves to the full path of the downloaded file
+       */
+      async download(imageUrl, destinationPath, options = {}) {
+        const url = typeof imageUrl === "string" ? imageUrl : imageUrl.url;
+        if (!fs.existsSync(destinationPath)) {
+          fs.mkdirSync(destinationPath, { recursive: true });
+        }
+        let finalFilename;
+        if (options.filename) {
+          finalFilename = options.filename;
+        } else if (options.keepOriginalName) {
+          const urlPath = new URL(url).pathname;
+          const urlFilename = path.basename(urlPath);
+          if (urlFilename && urlFilename.length > 0 && urlFilename !== "/") {
+            finalFilename = urlFilename;
+          } else {
+            const ext = this.getExtensionFromUrl(url) || ".jpg";
+            finalFilename = `${uuidv4()}${ext}`;
+          }
+        } else {
+          const ext = this.getExtensionFromUrl(url) || ".jpg";
+          finalFilename = `${uuidv4()}${ext}`;
+        }
+        if (!path.extname(finalFilename)) {
+          finalFilename += ".jpg";
+        }
+        const fullPath = path.join(destinationPath, finalFilename);
+        if (fs.existsSync(fullPath) && !options.overwrite) {
+          throw new Error(`File already exists: ${fullPath}. Set overwrite: true to replace it.`);
+        }
+        try {
+          const response = await axios4.get(url, {
+            responseType: "stream",
+            maxRedirects: 5
+            // Automatically handle redirects
+          });
+          const writer = fs.createWriteStream(fullPath);
+          response.data.pipe(writer);
+          return new Promise((resolve, reject) => {
+            writer.on("finish", () => {
+              resolve(fullPath);
+            });
+            writer.on("error", (err) => {
+              fs.unlink(fullPath, () => {
+              });
+              reject(err);
+            });
+            response.data.on("error", (err) => {
+              writer.close();
+              fs.unlink(fullPath, () => {
+              });
+              reject(err);
+            });
+          });
+        } catch (error) {
+          if (axios4.isAxiosError(error)) {
+            throw new Error(`Failed to download image: ${error.message}`);
+          }
+          throw error;
+        }
+      }
+      /**
+       * Helper method to extract file extension from URL
+       * @param url - The URL to extract extension from
+       * @returns The file extension (e.g., '.jpg', '.png') or null
+       */
+      getExtensionFromUrl(url) {
+        try {
+          const urlPath = new URL(url).pathname;
+          const ext = path.extname(urlPath);
+          return ext || null;
+        } catch {
+          return null;
+        }
+      }
+    };
+  }
+});
+
+// src/index.ts
+var init_index = __esm({
+  "src/index.ts"() {
+    "use strict";
+    init_types();
+    init_unsplash();
+    init_pexels();
+    init_pixabay();
+    init_image_fetcher();
+  }
+});
+
+// src/cli.ts
+import { Command } from "commander";
+import * as path2 from "path";
+import * as dotenv from "dotenv";
+import * as fs2 from "fs";
+var require_cli = __commonJS({
+  "src/cli.ts"() {
+    init_index();
+    var possibleEnvPaths = [
+      path2.resolve(process.cwd(), ".env"),
+      // Current working directory
+      path2.resolve(__dirname, ".env"),
+      // Same directory as the CLI script (dist/)
+      path2.resolve(__dirname, "..", ".env")
+      // Parent directory (root of project)
+    ];
+    for (const envPath of possibleEnvPaths) {
+      if (fs2.existsSync(envPath)) {
+        dotenv.config({ path: envPath });
+        console.log(`Loaded environment from: ${envPath}`);
+        break;
+      }
+    }
+    var program = new Command();
+    program.name("random-image").description("CLI tool to fetch random images from various providers").version("1.2.0");
+    program.command("fetch").description("Fetch a random image from image providers").option("-q, --query <search>", "Search query for the image").option("-w, --width <number>", "Width of the image", parseInt).option("-h, --height <number>", "Height of the image", parseInt).option("--quality <number>", "Quality of the image (0-100)", parseInt).option("--orientation <type>", "Image orientation (landscape or portrait)").option("-p, --provider <name>", "Provider to use (unsplash, pexels, pixabay, or random)", "random").option("-d, --download [path]", "Download the image to specified directory (default: ./downloads)").option("--filename <name>", "Custom filename for downloaded image").option("--overwrite", "Overwrite existing files", false).option("--no-keep-original-name", "Generate random UUID filename instead of keeping original").action(async (options) => {
+      try {
+        const providers = {
+          unsplash: process.env.UNSPLASH_KEY,
+          pexels: process.env.PEXELS_KEY,
+          pixabay: process.env.PIXABAY_KEY
+        };
+        let providerName = options.provider.toLowerCase();
+        if (providerName === "random") {
+          const availableProviders = Object.entries(providers).filter(([_, key]) => key).map(([name]) => name);
+          if (availableProviders.length === 0) {
+            console.error("Error: No API keys found in environment variables.");
+            console.error("Please set at least one of: UNSPLASH_KEY, PEXELS_KEY, PIXABAY_KEY");
+            process.exit(1);
+          }
+          providerName = availableProviders[Math.floor(Math.random() * availableProviders.length)];
+          console.log(`Using random provider: ${providerName}`);
+        }
+        let provider;
+        const apiKey = providers[providerName];
+        if (!apiKey) {
+          console.error(`Error: API key for ${providerName} not found.`);
+          console.error(`Please set ${providerName.toUpperCase()}_KEY environment variable.`);
+          process.exit(1);
+        }
+        switch (providerName) {
+          case "unsplash":
+            provider = new UnsplashProvider(apiKey);
+            break;
+          case "pexels":
+            provider = new PexelsProvider(apiKey);
+            break;
+          case "pixabay":
+            provider = new PixabayProvider(apiKey);
+            break;
+          default:
+            console.error(`Error: Unknown provider "${providerName}"`);
+            console.error("Available providers: unsplash, pexels, pixabay, random");
+            process.exit(1);
+        }
+        const fetcher = new RandomImage(provider);
+        const fetchOptions = {};
+        if (options.query) fetchOptions.query = options.query;
+        if (options.width) fetchOptions.width = options.width;
+        if (options.height) fetchOptions.height = options.height;
+        if (options.quality) fetchOptions.quality = options.quality;
+        if (options.orientation) fetchOptions.orientation = options.orientation;
+        console.log("Fetching random image...");
+        const image = await fetcher.getRandom(fetchOptions);
+        console.log("\n\u2713 Image fetched successfully!");
+        console.log(`  URL: ${image.url}`);
+        console.log(`  Size: ${image.width}x${image.height}`);
+        console.log(`  Author: ${image.author}`);
+        if (image.authorUrl) console.log(`  Author URL: ${image.authorUrl}`);
+        console.log(`  Original: ${image.originalUrl}`);
+        if (options.download !== void 0) {
+          const downloadPath = typeof options.download === "string" ? options.download : "./downloads";
+          console.log(`
+Downloading to ${path2.resolve(downloadPath)}...`);
+          const downloadOptions = {
+            overwrite: options.overwrite,
+            keepOriginalName: options.keepOriginalName
+          };
+          if (options.filename) {
+            downloadOptions.filename = options.filename;
+          }
+          const filePath = await fetcher.download(image, downloadPath, downloadOptions);
+          console.log(`\u2713 Downloaded: ${filePath}`);
+        }
+      } catch (error) {
+        if (error instanceof Error) {
+          console.error(`
+Error: ${error.message}`);
+        } else {
+          console.error("\nAn unexpected error occurred");
+        }
+        process.exit(1);
+      }
+    });
+    program.parse(process.argv);
+  }
+});
+export default require_cli();

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@nghiavuive/random-image",
-  "version": "1.1.0",
-  "description": "",
+  "version": "1.2.0",
+  "description": "Fetch random images from Unsplash, Pexels, and Pixabay with CLI support",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",
   "types": "./dist/index.d.ts",
@@ -32,13 +32,17 @@
   "devDependencies": {
     "@types/node": "^25.2.0",
     "@types/uuid": "^10.0.0",
-    "dotenv": "^17.2.3",
     "tsup": "^8.5.1",
     "typescript": "^5.9.3",
     "vitest": "^4.0.18"
   },
   "dependencies": {
     "axios": "^1.13.4",
+    "commander": "^12.1.0",
+    "dotenv": "^17.2.3",
     "uuid": "^13.0.0"
+  },
+  "bin": {
+    "random-image": "./dist/cli.js"
   }
 }