@nghiavuive/random-image 1.0.2 → 1.2.0

package/README.md

@@ -1,46 +1,196 @@
 # random-image
 
-A generic utility library to fetch random images from various providers like Unsplash and Pexels.
+A generic utility library to fetch random images from various providers like Unsplash and Pexels, with built-in download capabilities and CLI support.
 
 ## Installation
 
 ```bash
-npm install random-image
+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)
 - [Pexels API](https://www.pexels.com/api/)
 
+### Basic Usage - Fetching Random Images
+
 ```typescript
-import { RandomImage, UnsplashProvider, PexelsProvider } from 'random-image';
+import { RandomImage, UnsplashProvider, PexelsProvider } from '@nghiavuive/random-image';
 
 // Using Unsplash
 const unsplash = new UnsplashProvider('YOUR_UNSPLASH_ACCESS_KEY');
 const fetcher = new RandomImage(unsplash);
 
-fetcher.getRandom({
+const image = await fetcher.getRandom({
     width: 1920,
     height: 1080,
     query: 'nature'
-}).then(image => {
-    console.log(image.url); // URL to the image
-    console.log(image.author); // Photographer's name
 });
 
+console.log(image.url); // URL to the image
+console.log(image.author); // Photographer's name
+
 // Using Pexels
 const pexels = new PexelsProvider('YOUR_PEXELS_API_KEY');
 const pexelsFetcher = new RandomImage(pexels);
 
-pexelsFetcher.getRandom({
+const pexelsImage = await pexelsFetcher.getRandom({
     width: 800,
     height: 600,
     query: 'cats'
-}).then(image => {
-    console.log(image.url);
 });
+
+console.log(pexelsImage.url);
+```
+
+### Downloading Images
+
+The library now supports downloading images directly to your local filesystem:
+
+```typescript
+import { RandomImage, UnsplashProvider } from '@nghiavuive/random-image';
+
+const provider = new UnsplashProvider('YOUR_API_KEY');
+const fetcher = new RandomImage(provider);
+
+// Fetch and download a random image
+const image = await fetcher.getRandom({ query: 'mountains' });
+
+// Download with auto-generated filename
+const filePath = await fetcher.download(image, './downloads');
+console.log(`Image saved to: ${filePath}`);
+
+// Download with custom filename
+const customPath = await fetcher.download(
+    image, 
+    './downloads',
+    { filename: 'my-mountain.jpg' }
+);
+
+// Download with overwrite option
+const overwritePath = await fetcher.download(
+    image,
+    './downloads',
+    { 
+        filename: 'mountain.jpg',
+        overwrite: true  // Will replace existing file
+    }
+);
+
+// Download directly from URL
+await fetcher.download(
+    'https://example.com/image.jpg',
+    './downloads',
+    { filename: 'direct-download.jpg' }
+);
+
+// Download with UUID-based random filename
+await fetcher.download(
+    image,
+    './downloads',
+    { keepOriginalName: false }
+);
+
+// Download keeping original filename (default behavior)
+await fetcher.download(
+    image,
+    './downloads',
+    { keepOriginalName: true }
+);
 ```
 
 ## API
@@ -51,24 +201,74 @@ The main class to interact with.
 ```typescript
 class RandomImage {
     constructor(provider: ImageProvider);
+    
+    // Fetch a random image
     getRandom(options: ImageOptions): Promise<ImageResult>;
+    
+    // Download an image to local filesystem
+    download(
+        imageUrl: string | ImageResult,
+        destinationPath: string,
+        options?: DownloadOptions
+    ): Promise<string>;
 }
 ```
 
 ### `ImageOptions`
-- `width` (number): Desired width of the image.
-- `height` (number): Desired height of the image.
-- `quality` (number): Quality (0-100) if supported.
-- `query` (string): Search query (e.g. "nature", "city").
+Configuration for fetching random images:
+- `width` (number, optional): Desired width of the image.
+- `height` (number, optional): Desired height of the image.
+- `quality` (number, optional): Quality (0-100) if supported by provider.
+- `query` (string, optional): Search query (e.g. "nature", "city").
+- `orientation` ("landscape" | "portrait", optional): Image orientation.
+
+### `DownloadOptions`
+Configuration for downloading images:
+- `filename` (string, optional): Custom filename for the downloaded image. If provided, this takes precedence over `keepOriginalName`.
+- `overwrite` (boolean, optional): Whether to overwrite existing files. Default is `false`. If `false` and file exists, an error will be thrown.
+- `keepOriginalName` (boolean, optional): Controls filename generation when `filename` is not provided:
+  - `true` or `undefined` (default): Extract and use the original filename from the URL
+  - `false`: Generate a random UUID-based filename
 
 ### `ImageResult`
+Result object containing image information:
 - `url` (string): Direct URL to the image.
 - `width` (number): Width of the image.
 - `height` (number): Height of the image.
 - `author` (string): Name of the photographer.
-- `authorUrl` (string): URL to photographer's profile.
+- `authorUrl` (string, optional): URL to photographer's profile.
 - `originalUrl` (string): URL to the original photo page.
 
+## 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
+- ✅ Flexible filename options:
+  - Custom filename
+  - Keep original filename from URL (default)
+  - Generate random UUID-based filename
+- ✅ Overwrite protection
+- ✅ Automatic file extension detection
+- ✅ Support for both HTTP and HTTPS
+- ✅ Automatic redirect handling (up to 5 redirects)
+- ✅ Stream-based downloading for memory efficiency
+- ✅ Error handling with cleanup of partial downloads
+
+## Supported Providers
+
+- **Unsplash**: High-quality photos with attribution
+- **Pexels**: Free stock photos and videos
+- **Pixabay**: Free images and videos
+
 ## License
 
 ISC
+

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);