@nghiavuive/random-image 1.0.0 → 1.1.0

package/README.md

@@ -1,11 +1,11 @@
 # 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.
 
 ## Installation
 
 ```bash
-npm install random-image
+npm install @nghiavuive/random-image
 ```
 
 ## Usage
@@ -14,33 +14,91 @@ 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 +109,66 @@ 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
+
+### Download Functionality
+- ✅ Automatic directory creation
+- ✅ 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/index.d.mts

@@ -3,6 +3,7 @@ interface ImageOptions {
     height?: number;
     quality?: number;
     query?: string;
+    orientation?: "landscape" | "portrait";
 }
 interface ImageResult {
     url: string;
@@ -15,6 +16,11 @@ interface ImageResult {
 interface ImageProvider {
     fetchRandomImage(options: ImageOptions): Promise<ImageResult>;
 }
+interface DownloadOptions {
+    filename?: string;
+    overwrite?: boolean;
+    keepOriginalName?: boolean;
+}
 
 declare class UnsplashProvider implements ImageProvider {
     private accessKey;
@@ -28,6 +34,12 @@ declare class PexelsProvider implements ImageProvider {
     fetchRandomImage(options: ImageOptions): Promise<ImageResult>;
 }
 
+declare class PixabayProvider implements ImageProvider {
+    private apiKey;
+    constructor(apiKey: string);
+    fetchRandomImage(options: ImageOptions): Promise<ImageResult>;
+}
+
 declare class RandomImage {
     private provider;
     constructor(provider: ImageProvider);
@@ -37,6 +49,20 @@ declare class RandomImage {
      * @returns A promise that resolves to an ImageResult object.
      */
     getRandom(options?: ImageOptions): Promise<ImageResult>;
+    /**
+     * 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
+     */
+    download(imageUrl: string | ImageResult, destinationPath: string, options?: DownloadOptions): Promise<string>;
+    /**
+     * 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
+     */
+    private getExtensionFromUrl;
 }
 
-export { type ImageOptions, type ImageProvider, type ImageResult, PexelsProvider, RandomImage, UnsplashProvider };
+export { type DownloadOptions, type ImageOptions, type ImageProvider, type ImageResult, PexelsProvider, PixabayProvider, RandomImage, UnsplashProvider };

package/dist/index.d.ts

@@ -3,6 +3,7 @@ interface ImageOptions {
     height?: number;
     quality?: number;
     query?: string;
+    orientation?: "landscape" | "portrait";
 }
 interface ImageResult {
     url: string;
@@ -15,6 +16,11 @@ interface ImageResult {
 interface ImageProvider {
     fetchRandomImage(options: ImageOptions): Promise<ImageResult>;
 }
+interface DownloadOptions {
+    filename?: string;
+    overwrite?: boolean;
+    keepOriginalName?: boolean;
+}
 
 declare class UnsplashProvider implements ImageProvider {
     private accessKey;
@@ -28,6 +34,12 @@ declare class PexelsProvider implements ImageProvider {
     fetchRandomImage(options: ImageOptions): Promise<ImageResult>;
 }
 
+declare class PixabayProvider implements ImageProvider {
+    private apiKey;
+    constructor(apiKey: string);
+    fetchRandomImage(options: ImageOptions): Promise<ImageResult>;
+}
+
 declare class RandomImage {
     private provider;
     constructor(provider: ImageProvider);
@@ -37,6 +49,20 @@ declare class RandomImage {
      * @returns A promise that resolves to an ImageResult object.
      */
     getRandom(options?: ImageOptions): Promise<ImageResult>;
+    /**
+     * 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
+     */
+    download(imageUrl: string | ImageResult, destinationPath: string, options?: DownloadOptions): Promise<string>;
+    /**
+     * 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
+     */
+    private getExtensionFromUrl;
 }
 
-export { type ImageOptions, type ImageProvider, type ImageResult, PexelsProvider, RandomImage, UnsplashProvider };
+export { type DownloadOptions, type ImageOptions, type ImageProvider, type ImageResult, PexelsProvider, PixabayProvider, RandomImage, UnsplashProvider };

package/dist/index.js

@@ -1,7 +1,9 @@
 "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 __export = (target, all) => {
   for (var name in all)
@@ -15,38 +17,50 @@ var __copyProps = (to, from, except, desc) => {
   }
   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
+));
 var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
 
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
   PexelsProvider: () => PexelsProvider,
+  PixabayProvider: () => PixabayProvider,
   RandomImage: () => RandomImage,
   UnsplashProvider: () => UnsplashProvider
 });
 module.exports = __toCommonJS(index_exports);
 
 // src/providers/unsplash.ts
+var import_axios = __toESM(require("axios"));
 var UnsplashProvider = class {
   constructor(accessKey) {
     this.accessKey = accessKey;
   }
   async fetchRandomImage(options) {
-    const params = new URLSearchParams();
-    if (options.query) params.append("query", options.query);
-    const url = `https://api.unsplash.com/photos/random?${params.toString()}`;
-    const response = await fetch(url, {
+    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
       }
     });
-    if (!response.ok) {
-      throw new Error(`Unsplash API error: ${response.statusText}`);
-    }
-    const data = await response.json();
+    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());
@@ -64,6 +78,7 @@ var UnsplashProvider = class {
 };
 
 // src/providers/pexels.ts
+var import_axios2 = __toESM(require("axios"));
 var PexelsProvider = class {
   constructor(apiKey) {
     this.apiKey = apiKey;
@@ -71,19 +86,18 @@ var PexelsProvider = class {
   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 = new URLSearchParams();
-    if (options.query) params.append("query", options.query);
-    params.append("per_page", "1");
-    params.append("page", randomPage.toString());
-    const response = await fetch(`${endpoint}?${params.toString()}`, {
+    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
     });
-    if (!response.ok) {
-      throw new Error(`Pexels API error: ${response.statusText}`);
-    }
-    const data = await response.json();
+    const data = response.data;
     if (!data.photos || data.photos.length === 0) {
       throw new Error("No images found on Pexels");
     }
@@ -106,7 +120,46 @@ var PexelsProvider = class {
   }
 };
 
+// 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;
@@ -119,10 +172,91 @@ var RandomImage = class {
   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((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 (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;
+    }
+  }
 };
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   PexelsProvider,
+  PixabayProvider,
   RandomImage,
   UnsplashProvider
 });

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/index.ts","../src/providers/unsplash.ts","../src/providers/pexels.ts","../src/image-fetcher.ts"],"sourcesContent":["export * from './types';\nexport * from './providers/unsplash';\nexport * from './providers/pexels';\nexport * from './image-fetcher';\n","import { ImageProvider, ImageOptions, ImageResult } from '../types';\n\nexport class UnsplashProvider implements ImageProvider {\n  private accessKey: string;\n\n  constructor(accessKey: string) {\n    this.accessKey = accessKey;\n  }\n\n  async fetchRandomImage(options: ImageOptions): Promise<ImageResult> {\n    const params = new URLSearchParams();\n    if (options.query) params.append('query', options.query);\n    // Unsplash doesn't strictly support width/height for random photo selection in the same way for resizing via API query params on the /random endpoint directly for *fetching* the image content, \n    // but we can request specific dimensions roughly or rely on the returned structure to pick a size.\n    // However, the /photos/random endpoint returns a JSON with urls.raw, urls.full, etc.\n    // We can append parameters to the returned URL for resizing.\n    \n    // Using fetching logic:\n    const url = `https://api.unsplash.com/photos/random?${params.toString()}`;\n    \n    const response = await fetch(url, {\n      headers: {\n        Authorization: `Client-ID ${this.accessKey}`\n      }\n    });\n\n    if (!response.ok) {\n        throw new Error(`Unsplash API error: ${response.statusText}`);\n    }\n\n    const data = await response.json();\n    \n    // Handle single random photo (array if count param used, but here generic assumes one)\n    const photo = Array.isArray(data) ? data[0] : data;\n\n    // Construct resized URL\n    // Unsplash uses Imgix. We can append parameters.\n    const baseUrl = photo.urls.raw;\n    const sizeParams = new URLSearchParams();\n    if (options.width) sizeParams.append('w', options.width.toString());\n    if (options.height) sizeParams.append('h', options.height.toString());\n    if (options.quality) sizeParams.append('q', options.quality.toString());\n    \n    const finalUrl = `${baseUrl}&${sizeParams.toString()}`;\n\n    return {\n      url: finalUrl,\n      width: options.width || photo.width,\n      height: options.height || photo.height,\n      author: photo.user.name,\n      authorUrl: photo.user.links.html,\n      originalUrl: photo.links.html // Link to photo page\n    };\n  }\n}\n","import { ImageProvider, ImageOptions, ImageResult } from '../types';\n\nexport class PexelsProvider implements ImageProvider {\n  private apiKey: string;\n\n  constructor(apiKey: string) {\n    this.apiKey = apiKey;\n  }\n\n  async fetchRandomImage(options: ImageOptions): Promise<ImageResult> {\n    // Pexels 'curated' or 'search'. \n    // If query is present, use search. If not, use curated.\n    // We need to randomize the result because Pexels search/curated returns a list.\n    // We can use 'page' and 'per_page=1' with a random page number to simulate random? \n    // Or just fetch one page and pick random?\n    // Pexels API doesn't have a direct /random endpoint like Unsplash.\n    // Efficient strategy: Search with 1 result per page, but randomize the page number.\n    // Max page is tricky, maybe limit to top 100 results?\n    \n    const endpoint = options.query \n        ? 'https://api.pexels.com/v1/search' \n        : 'https://api.pexels.com/v1/curated';\n\n    // Randomizing page number (1-100) to get a \"random\" image\n    const randomPage = Math.floor(Math.random() * 100) + 1;\n    \n    const params = new URLSearchParams();\n    if (options.query) params.append('query', options.query);\n    params.append('per_page', '1');\n    params.append('page', randomPage.toString());\n\n    const response = await fetch(`${endpoint}?${params.toString()}`, {\n      headers: {\n        Authorization: this.apiKey\n      }\n    });\n\n    if (!response.ok) {\n      throw new Error(`Pexels API error: ${response.statusText}`);\n    }\n\n    const data = await response.json();\n    \n    if (!data.photos || data.photos.length === 0) {\n        throw new Error('No images found on Pexels');\n    }\n\n    const photo = data.photos[0];\n\n    // Pexels supports resizing via query params on the image url?\n    // Pexels returns src object with original, large2x, large, medium, small, portrait, landscape, tiny.\n    // Or we can modify the 'original' url.\n    // Pexels docs say: https://images.pexels.com/photos/2014422/pexels-photo-2014422.jpeg?auto=compress&cs=tinysrgb&h=350\n    \n    const baseUrl = photo.src.original;\n    const sizeParams = new URLSearchParams();\n    sizeParams.append('auto', 'compress');\n    sizeParams.append('cs', 'tinysrgb'); // Default pexels param\n    if (options.width) sizeParams.append('w', options.width.toString());\n    if (options.height) sizeParams.append('h', options.height.toString());\n    \n    // Note: Quality param is not standard in Pexels URL manipulation documented publicly as 'q', \n    // but 'auto=compress' handles it. We can try adding it if needed or ignore. \n    // I'll skip explicit q param mapping for now as it's not strictly 'quality=X'.\n\n    const finalUrl = `${baseUrl}?${sizeParams.toString()}`;\n\n    return {\n      url: finalUrl,\n      width: options.width || photo.width,\n      height: options.height || photo.height,\n      author: photo.photographer,\n      authorUrl: photo.photographer_url,\n      originalUrl: photo.url\n    };\n  }\n}\n","import { ImageProvider, ImageOptions, ImageResult } from './types';\n\nexport class RandomImage {\n  private provider: ImageProvider;\n\n  constructor(provider: ImageProvider) {\n    this.provider = provider;\n  }\n\n  /**\n   * Fetches a random image based on the provided options.\n   * @param options - Configuration options for the image (width, height, query, etc.)\n   * @returns A promise that resolves to an ImageResult object.\n   */\n  async getRandom(options: ImageOptions = {}): Promise<ImageResult> {\n    return this.provider.fetchRandomImage(options);\n  }\n}\n"],"mappings":"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","names":[]}
+{"version":3,"sources":["../src/index.ts","../src/providers/unsplash.ts","../src/providers/pexels.ts","../src/providers/pixabay.ts","../src/image-fetcher.ts"],"sourcesContent":["export * from \"./types\";\nexport * from \"./providers/unsplash\";\nexport * from \"./providers/pexels\";\nexport * from \"./providers/pixabay\";\nexport * from \"./image-fetcher\";\n","import axios from \"axios\";\nimport { ImageProvider, ImageOptions, ImageResult } from \"../types\";\n\nexport class UnsplashProvider implements ImageProvider {\n  private accessKey: string;\n\n  constructor(accessKey: string) {\n    this.accessKey = accessKey;\n  }\n\n  async fetchRandomImage(options: ImageOptions): Promise<ImageResult> {\n    const response = await axios.get(\"https://api.unsplash.com/photos/random\", {\n      headers: {\n        Authorization: `Client-ID ${this.accessKey}`,\n      },\n      params: {\n        query: options.query,\n        orientation: options.orientation,\n      },\n    });\n\n    const data = response.data;\n\n    // Handle single random photo (array if count param used, but here generic assumes one)\n    const photo = Array.isArray(data) ? data[0] : data;\n\n    // Construct resized URL\n    // Unsplash uses Imgix. We can append parameters.\n    const baseUrl = photo.urls.raw;\n    const sizeParams = new URLSearchParams();\n    if (options.height || options.width) {\n      sizeParams.append(\"fit\", \"crop\");\n      sizeParams.append(\"crop\", \"entropy\");\n    }\n    if (options.width) sizeParams.append(\"w\", options.width.toString());\n    if (options.height) sizeParams.append(\"h\", options.height.toString());\n    if (options.quality) sizeParams.append(\"q\", options.quality.toString());\n\n    const finalUrl = `${baseUrl}&${sizeParams.toString()}`;\n\n    return {\n      url: finalUrl,\n      width: options.width || photo.width,\n      height: options.height || photo.height,\n      author: photo.user.name,\n      authorUrl: photo.user.links.html,\n      originalUrl: photo.links.html, // Link to photo page\n    };\n  }\n}\n","import axios from \"axios\";\nimport { ImageProvider, ImageOptions, ImageResult } from \"../types\";\n\nexport class PexelsProvider implements ImageProvider {\n  private apiKey: string;\n\n  constructor(apiKey: string) {\n    this.apiKey = apiKey;\n  }\n\n  async fetchRandomImage(options: ImageOptions): Promise<ImageResult> {\n    const endpoint = options.query\n      ? \"https://api.pexels.com/v1/search\"\n      : \"https://api.pexels.com/v1/curated\";\n\n    // Randomizing page number (1-100) to get a \"random\" image\n    const randomPage = Math.floor(Math.random() * 100) + 1;\n\n    const params: any = {\n      per_page: 1,\n      page: randomPage,\n    };\n    if (options.query) params.query = options.query;\n\n    const response = await axios.get(endpoint, {\n      headers: {\n        Authorization: this.apiKey,\n      },\n      params: params,\n    });\n\n    const data = response.data;\n\n    if (!data.photos || data.photos.length === 0) {\n      throw new Error(\"No images found on Pexels\");\n    }\n\n    const photo = data.photos[0];\n\n    const baseUrl = photo.src.original;\n    const sizeParams = new URLSearchParams();\n    sizeParams.append(\"auto\", \"compress\");\n    sizeParams.append(\"cs\", \"tinysrgb\"); // Default pexels param\n    if (options.width) sizeParams.append(\"w\", options.width.toString());\n    if (options.height) sizeParams.append(\"h\", options.height.toString());\n\n    const finalUrl = `${baseUrl}?${sizeParams.toString()}`;\n\n    return {\n      url: finalUrl,\n      width: options.width || photo.width,\n      height: options.height || photo.height,\n      author: photo.photographer,\n      authorUrl: photo.photographer_url,\n      originalUrl: photo.url,\n    };\n  }\n}\n","import axios from \"axios\";\nimport { ImageProvider, ImageOptions, ImageResult } from \"../types\";\n\nexport class PixabayProvider implements ImageProvider {\n  private apiKey: string;\n\n  constructor(apiKey: string) {\n    this.apiKey = apiKey;\n  }\n\n  async fetchRandomImage(options: ImageOptions): Promise<ImageResult> {\n    const params: any = {\n      key: this.apiKey,\n      q: options.query || \"\",\n      per_page: 20, // Fetch a few to pick randomly\n    };\n\n    if (options.orientation) {\n      params.orientation =\n        options.orientation === \"portrait\" ? \"vertical\" : \"horizontal\";\n    }\n\n    const response = await axios.get(\"https://pixabay.com/api/\", {\n      params,\n    });\n\n    const hits = response.data.hits;\n\n    if (!hits || hits.length === 0) {\n      throw new Error(\"No images found\");\n    }\n\n    // Pick a random hit\n    const randomHit = hits[Math.floor(Math.random() * hits.length)];\n\n    return {\n      url: randomHit.largeImageURL || randomHit.webformatURL,\n      width: randomHit.imageWidth || randomHit.webformatWidth,\n      height: randomHit.imageHeight || randomHit.webformatHeight,\n      author: randomHit.user,\n      authorUrl: `https://pixabay.com/users/${randomHit.user}-${randomHit.user_id}/`,\n      originalUrl: randomHit.pageURL,\n    };\n  }\n}\n","import { ImageProvider, ImageOptions, ImageResult, DownloadOptions } from './types';\nimport * as fs from 'fs';\nimport * as path from 'path';\nimport axios from 'axios';\nimport { v7 as uuidv4 } from 'uuid';\n\nexport class RandomImage {\n  private provider: ImageProvider;\n\n  constructor(provider: ImageProvider) {\n    this.provider = provider;\n  }\n\n  /**\n   * Fetches a random image based on the provided options.\n   * @param options - Configuration options for the image (width, height, query, etc.)\n   * @returns A promise that resolves to an ImageResult object.\n   */\n  async getRandom(options: ImageOptions = {}): Promise<ImageResult> {\n    return this.provider.fetchRandomImage(options);\n  }\n\n  /**\n   * Downloads an image to a specified directory.\n   * @param imageUrl - The URL of the image to download (can be a string or ImageResult object)\n   * @param destinationPath - The directory path where the image will be saved\n   * @param options - Download options (filename, overwrite, etc.)\n   * @returns A promise that resolves to the full path of the downloaded file\n   */\n  async download(\n    imageUrl: string | ImageResult,\n    destinationPath: string,\n    options: DownloadOptions = {}\n  ): Promise<string> {\n    const url = typeof imageUrl === 'string' ? imageUrl : imageUrl.url;\n\n    // Create directory if it doesn't exist\n    if (!fs.existsSync(destinationPath)) {\n      fs.mkdirSync(destinationPath, { recursive: true });\n    }\n\n    // Determine filename\n    let finalFilename: string;\n    if (options.filename) {\n      finalFilename = options.filename;\n    } else if (options.keepOriginalName) {\n      // keepOriginalName === true or undefined (default behavior: try to keep original)\n      const urlPath = new URL(url).pathname;\n      const urlFilename = path.basename(urlPath);\n      if (urlFilename && urlFilename.length > 0 && urlFilename !== '/') {\n        finalFilename = urlFilename;\n      } else {\n        // Fallback if no filename in URL\n        const ext = this.getExtensionFromUrl(url) || '.jpg';\n        finalFilename = `${uuidv4()}${ext}`;\n      }\n    } else {\n      // Generate UUID v4 filename\n      const ext = this.getExtensionFromUrl(url) || '.jpg';\n      finalFilename = `${uuidv4()}${ext}`;\n    }\n\n    // Ensure filename has an extension\n    if (!path.extname(finalFilename)) {\n      finalFilename += '.jpg';\n    }\n\n    const fullPath = path.join(destinationPath, finalFilename);\n\n    // Check if file exists and overwrite option\n    if (fs.existsSync(fullPath) && !options.overwrite) {\n      throw new Error(`File already exists: ${fullPath}. Set overwrite: true to replace it.`);\n    }\n\n    try {\n      const response = await axios.get(url, {\n        responseType: 'stream',\n        maxRedirects: 5, // Automatically handle redirects\n      });\n\n      const writer = fs.createWriteStream(fullPath);\n\n      response.data.pipe(writer);\n\n      return new Promise((resolve, reject) => {\n        writer.on('finish', () => {\n          resolve(fullPath);\n        });\n\n        writer.on('error', (err) => {\n          fs.unlink(fullPath, () => { }); // Delete partial file\n          reject(err);\n        });\n\n        response.data.on('error', (err: Error) => {\n          writer.close();\n          fs.unlink(fullPath, () => { }); // Delete partial file\n          reject(err);\n        });\n      });\n    } catch (error) {\n      if (axios.isAxiosError(error)) {\n        throw new Error(`Failed to download image: ${error.message}`);\n      }\n      throw error;\n    }\n  }\n\n  /**\n   * Helper method to extract file extension from URL\n   * @param url - The URL to extract extension from\n   * @returns The file extension (e.g., '.jpg', '.png') or null\n   */\n  private getExtensionFromUrl(url: string): string | null {\n    try {\n      const urlPath = new URL(url).pathname;\n      const ext = path.extname(urlPath);\n      return ext || null;\n    } catch {\n      return null;\n    }\n  }\n}\n"],"mappings":"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","names":["axios","import_axios","axios","import_axios","axios","import_axios","uuidv4","axios"]}

package/dist/index.mjs

@@ -1,24 +1,27 @@
 // src/providers/unsplash.ts
+import axios from "axios";
 var UnsplashProvider = class {
   constructor(accessKey) {
     this.accessKey = accessKey;
   }
   async fetchRandomImage(options) {
-    const params = new URLSearchParams();
-    if (options.query) params.append("query", options.query);
-    const url = `https://api.unsplash.com/photos/random?${params.toString()}`;
-    const response = await fetch(url, {
+    const response = await axios.get("https://api.unsplash.com/photos/random", {
       headers: {
         Authorization: `Client-ID ${this.accessKey}`
+      },
+      params: {
+        query: options.query,
+        orientation: options.orientation
       }
     });
-    if (!response.ok) {
-      throw new Error(`Unsplash API error: ${response.statusText}`);
-    }
-    const data = await response.json();
+    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());
@@ -36,6 +39,7 @@ var UnsplashProvider = class {
 };
 
 // src/providers/pexels.ts
+import axios2 from "axios";
 var PexelsProvider = class {
   constructor(apiKey) {
     this.apiKey = apiKey;
@@ -43,19 +47,18 @@ var PexelsProvider = class {
   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 = new URLSearchParams();
-    if (options.query) params.append("query", options.query);
-    params.append("per_page", "1");
-    params.append("page", randomPage.toString());
-    const response = await fetch(`${endpoint}?${params.toString()}`, {
+    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
     });
-    if (!response.ok) {
-      throw new Error(`Pexels API error: ${response.statusText}`);
-    }
-    const data = await response.json();
+    const data = response.data;
     if (!data.photos || data.photos.length === 0) {
       throw new Error("No images found on Pexels");
     }
@@ -78,7 +81,46 @@ var PexelsProvider = class {
   }
 };
 
+// src/providers/pixabay.ts
+import axios3 from "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 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 = class {
   constructor(provider) {
     this.provider = provider;
@@ -91,9 +133,90 @@ var RandomImage = class {
   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;
+    }
+  }
 };
 export {
   PexelsProvider,
+  PixabayProvider,
   RandomImage,
   UnsplashProvider
 };

package/dist/index.mjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/providers/unsplash.ts","../src/providers/pexels.ts","../src/image-fetcher.ts"],"sourcesContent":["import { ImageProvider, ImageOptions, ImageResult } from '../types';\n\nexport class UnsplashProvider implements ImageProvider {\n  private accessKey: string;\n\n  constructor(accessKey: string) {\n    this.accessKey = accessKey;\n  }\n\n  async fetchRandomImage(options: ImageOptions): Promise<ImageResult> {\n    const params = new URLSearchParams();\n    if (options.query) params.append('query', options.query);\n    // Unsplash doesn't strictly support width/height for random photo selection in the same way for resizing via API query params on the /random endpoint directly for *fetching* the image content, \n    // but we can request specific dimensions roughly or rely on the returned structure to pick a size.\n    // However, the /photos/random endpoint returns a JSON with urls.raw, urls.full, etc.\n    // We can append parameters to the returned URL for resizing.\n    \n    // Using fetching logic:\n    const url = `https://api.unsplash.com/photos/random?${params.toString()}`;\n    \n    const response = await fetch(url, {\n      headers: {\n        Authorization: `Client-ID ${this.accessKey}`\n      }\n    });\n\n    if (!response.ok) {\n        throw new Error(`Unsplash API error: ${response.statusText}`);\n    }\n\n    const data = await response.json();\n    \n    // Handle single random photo (array if count param used, but here generic assumes one)\n    const photo = Array.isArray(data) ? data[0] : data;\n\n    // Construct resized URL\n    // Unsplash uses Imgix. We can append parameters.\n    const baseUrl = photo.urls.raw;\n    const sizeParams = new URLSearchParams();\n    if (options.width) sizeParams.append('w', options.width.toString());\n    if (options.height) sizeParams.append('h', options.height.toString());\n    if (options.quality) sizeParams.append('q', options.quality.toString());\n    \n    const finalUrl = `${baseUrl}&${sizeParams.toString()}`;\n\n    return {\n      url: finalUrl,\n      width: options.width || photo.width,\n      height: options.height || photo.height,\n      author: photo.user.name,\n      authorUrl: photo.user.links.html,\n      originalUrl: photo.links.html // Link to photo page\n    };\n  }\n}\n","import { ImageProvider, ImageOptions, ImageResult } from '../types';\n\nexport class PexelsProvider implements ImageProvider {\n  private apiKey: string;\n\n  constructor(apiKey: string) {\n    this.apiKey = apiKey;\n  }\n\n  async fetchRandomImage(options: ImageOptions): Promise<ImageResult> {\n    // Pexels 'curated' or 'search'. \n    // If query is present, use search. If not, use curated.\n    // We need to randomize the result because Pexels search/curated returns a list.\n    // We can use 'page' and 'per_page=1' with a random page number to simulate random? \n    // Or just fetch one page and pick random?\n    // Pexels API doesn't have a direct /random endpoint like Unsplash.\n    // Efficient strategy: Search with 1 result per page, but randomize the page number.\n    // Max page is tricky, maybe limit to top 100 results?\n    \n    const endpoint = options.query \n        ? 'https://api.pexels.com/v1/search' \n        : 'https://api.pexels.com/v1/curated';\n\n    // Randomizing page number (1-100) to get a \"random\" image\n    const randomPage = Math.floor(Math.random() * 100) + 1;\n    \n    const params = new URLSearchParams();\n    if (options.query) params.append('query', options.query);\n    params.append('per_page', '1');\n    params.append('page', randomPage.toString());\n\n    const response = await fetch(`${endpoint}?${params.toString()}`, {\n      headers: {\n        Authorization: this.apiKey\n      }\n    });\n\n    if (!response.ok) {\n      throw new Error(`Pexels API error: ${response.statusText}`);\n    }\n\n    const data = await response.json();\n    \n    if (!data.photos || data.photos.length === 0) {\n        throw new Error('No images found on Pexels');\n    }\n\n    const photo = data.photos[0];\n\n    // Pexels supports resizing via query params on the image url?\n    // Pexels returns src object with original, large2x, large, medium, small, portrait, landscape, tiny.\n    // Or we can modify the 'original' url.\n    // Pexels docs say: https://images.pexels.com/photos/2014422/pexels-photo-2014422.jpeg?auto=compress&cs=tinysrgb&h=350\n    \n    const baseUrl = photo.src.original;\n    const sizeParams = new URLSearchParams();\n    sizeParams.append('auto', 'compress');\n    sizeParams.append('cs', 'tinysrgb'); // Default pexels param\n    if (options.width) sizeParams.append('w', options.width.toString());\n    if (options.height) sizeParams.append('h', options.height.toString());\n    \n    // Note: Quality param is not standard in Pexels URL manipulation documented publicly as 'q', \n    // but 'auto=compress' handles it. We can try adding it if needed or ignore. \n    // I'll skip explicit q param mapping for now as it's not strictly 'quality=X'.\n\n    const finalUrl = `${baseUrl}?${sizeParams.toString()}`;\n\n    return {\n      url: finalUrl,\n      width: options.width || photo.width,\n      height: options.height || photo.height,\n      author: photo.photographer,\n      authorUrl: photo.photographer_url,\n      originalUrl: photo.url\n    };\n  }\n}\n","import { ImageProvider, ImageOptions, ImageResult } from './types';\n\nexport class RandomImage {\n  private provider: ImageProvider;\n\n  constructor(provider: ImageProvider) {\n    this.provider = provider;\n  }\n\n  /**\n   * Fetches a random image based on the provided options.\n   * @param options - Configuration options for the image (width, height, query, etc.)\n   * @returns A promise that resolves to an ImageResult object.\n   */\n  async getRandom(options: ImageOptions = {}): Promise<ImageResult> {\n    return this.provider.fetchRandomImage(options);\n  }\n}\n"],"mappings":";AAEO,IAAM,mBAAN,MAAgD;AAAA,EAGrD,YAAY,WAAmB;AAC7B,SAAK,YAAY;AAAA,EACnB;AAAA,EAEA,MAAM,iBAAiB,SAA6C;AAClE,UAAM,SAAS,IAAI,gBAAgB;AACnC,QAAI,QAAQ,MAAO,QAAO,OAAO,SAAS,QAAQ,KAAK;AAOvD,UAAM,MAAM,0CAA0C,OAAO,SAAS,CAAC;AAEvE,UAAM,WAAW,MAAM,MAAM,KAAK;AAAA,MAChC,SAAS;AAAA,QACP,eAAe,aAAa,KAAK,SAAS;AAAA,MAC5C;AAAA,IACF,CAAC;AAED,QAAI,CAAC,SAAS,IAAI;AACd,YAAM,IAAI,MAAM,uBAAuB,SAAS,UAAU,EAAE;AAAA,IAChE;AAEA,UAAM,OAAO,MAAM,SAAS,KAAK;AAGjC,UAAM,QAAQ,MAAM,QAAQ,IAAI,IAAI,KAAK,CAAC,IAAI;AAI9C,UAAM,UAAU,MAAM,KAAK;AAC3B,UAAM,aAAa,IAAI,gBAAgB;AACvC,QAAI,QAAQ,MAAO,YAAW,OAAO,KAAK,QAAQ,MAAM,SAAS,CAAC;AAClE,QAAI,QAAQ,OAAQ,YAAW,OAAO,KAAK,QAAQ,OAAO,SAAS,CAAC;AACpE,QAAI,QAAQ,QAAS,YAAW,OAAO,KAAK,QAAQ,QAAQ,SAAS,CAAC;AAEtE,UAAM,WAAW,GAAG,OAAO,IAAI,WAAW,SAAS,CAAC;AAEpD,WAAO;AAAA,MACL,KAAK;AAAA,MACL,OAAO,QAAQ,SAAS,MAAM;AAAA,MAC9B,QAAQ,QAAQ,UAAU,MAAM;AAAA,MAChC,QAAQ,MAAM,KAAK;AAAA,MACnB,WAAW,MAAM,KAAK,MAAM;AAAA,MAC5B,aAAa,MAAM,MAAM;AAAA;AAAA,IAC3B;AAAA,EACF;AACF;;;ACpDO,IAAM,iBAAN,MAA8C;AAAA,EAGnD,YAAY,QAAgB;AAC1B,SAAK,SAAS;AAAA,EAChB;AAAA,EAEA,MAAM,iBAAiB,SAA6C;AAUlE,UAAM,WAAW,QAAQ,QACnB,qCACA;AAGN,UAAM,aAAa,KAAK,MAAM,KAAK,OAAO,IAAI,GAAG,IAAI;AAErD,UAAM,SAAS,IAAI,gBAAgB;AACnC,QAAI,QAAQ,MAAO,QAAO,OAAO,SAAS,QAAQ,KAAK;AACvD,WAAO,OAAO,YAAY,GAAG;AAC7B,WAAO,OAAO,QAAQ,WAAW,SAAS,CAAC;AAE3C,UAAM,WAAW,MAAM,MAAM,GAAG,QAAQ,IAAI,OAAO,SAAS,CAAC,IAAI;AAAA,MAC/D,SAAS;AAAA,QACP,eAAe,KAAK;AAAA,MACtB;AAAA,IACF,CAAC;AAED,QAAI,CAAC,SAAS,IAAI;AAChB,YAAM,IAAI,MAAM,qBAAqB,SAAS,UAAU,EAAE;AAAA,IAC5D;AAEA,UAAM,OAAO,MAAM,SAAS,KAAK;AAEjC,QAAI,CAAC,KAAK,UAAU,KAAK,OAAO,WAAW,GAAG;AAC1C,YAAM,IAAI,MAAM,2BAA2B;AAAA,IAC/C;AAEA,UAAM,QAAQ,KAAK,OAAO,CAAC;AAO3B,UAAM,UAAU,MAAM,IAAI;AAC1B,UAAM,aAAa,IAAI,gBAAgB;AACvC,eAAW,OAAO,QAAQ,UAAU;AACpC,eAAW,OAAO,MAAM,UAAU;AAClC,QAAI,QAAQ,MAAO,YAAW,OAAO,KAAK,QAAQ,MAAM,SAAS,CAAC;AAClE,QAAI,QAAQ,OAAQ,YAAW,OAAO,KAAK,QAAQ,OAAO,SAAS,CAAC;AAMpE,UAAM,WAAW,GAAG,OAAO,IAAI,WAAW,SAAS,CAAC;AAEpD,WAAO;AAAA,MACL,KAAK;AAAA,MACL,OAAO,QAAQ,SAAS,MAAM;AAAA,MAC9B,QAAQ,QAAQ,UAAU,MAAM;AAAA,MAChC,QAAQ,MAAM;AAAA,MACd,WAAW,MAAM;AAAA,MACjB,aAAa,MAAM;AAAA,IACrB;AAAA,EACF;AACF;;;AC1EO,IAAM,cAAN,MAAkB;AAAA,EAGvB,YAAY,UAAyB;AACnC,SAAK,WAAW;AAAA,EAClB;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAOA,MAAM,UAAU,UAAwB,CAAC,GAAyB;AAChE,WAAO,KAAK,SAAS,iBAAiB,OAAO;AAAA,EAC/C;AACF;","names":[]}
+{"version":3,"sources":["../src/providers/unsplash.ts","../src/providers/pexels.ts","../src/providers/pixabay.ts","../src/image-fetcher.ts"],"sourcesContent":["import axios from \"axios\";\nimport { ImageProvider, ImageOptions, ImageResult } from \"../types\";\n\nexport class UnsplashProvider implements ImageProvider {\n  private accessKey: string;\n\n  constructor(accessKey: string) {\n    this.accessKey = accessKey;\n  }\n\n  async fetchRandomImage(options: ImageOptions): Promise<ImageResult> {\n    const response = await axios.get(\"https://api.unsplash.com/photos/random\", {\n      headers: {\n        Authorization: `Client-ID ${this.accessKey}`,\n      },\n      params: {\n        query: options.query,\n        orientation: options.orientation,\n      },\n    });\n\n    const data = response.data;\n\n    // Handle single random photo (array if count param used, but here generic assumes one)\n    const photo = Array.isArray(data) ? data[0] : data;\n\n    // Construct resized URL\n    // Unsplash uses Imgix. We can append parameters.\n    const baseUrl = photo.urls.raw;\n    const sizeParams = new URLSearchParams();\n    if (options.height || options.width) {\n      sizeParams.append(\"fit\", \"crop\");\n      sizeParams.append(\"crop\", \"entropy\");\n    }\n    if (options.width) sizeParams.append(\"w\", options.width.toString());\n    if (options.height) sizeParams.append(\"h\", options.height.toString());\n    if (options.quality) sizeParams.append(\"q\", options.quality.toString());\n\n    const finalUrl = `${baseUrl}&${sizeParams.toString()}`;\n\n    return {\n      url: finalUrl,\n      width: options.width || photo.width,\n      height: options.height || photo.height,\n      author: photo.user.name,\n      authorUrl: photo.user.links.html,\n      originalUrl: photo.links.html, // Link to photo page\n    };\n  }\n}\n","import axios from \"axios\";\nimport { ImageProvider, ImageOptions, ImageResult } from \"../types\";\n\nexport class PexelsProvider implements ImageProvider {\n  private apiKey: string;\n\n  constructor(apiKey: string) {\n    this.apiKey = apiKey;\n  }\n\n  async fetchRandomImage(options: ImageOptions): Promise<ImageResult> {\n    const endpoint = options.query\n      ? \"https://api.pexels.com/v1/search\"\n      : \"https://api.pexels.com/v1/curated\";\n\n    // Randomizing page number (1-100) to get a \"random\" image\n    const randomPage = Math.floor(Math.random() * 100) + 1;\n\n    const params: any = {\n      per_page: 1,\n      page: randomPage,\n    };\n    if (options.query) params.query = options.query;\n\n    const response = await axios.get(endpoint, {\n      headers: {\n        Authorization: this.apiKey,\n      },\n      params: params,\n    });\n\n    const data = response.data;\n\n    if (!data.photos || data.photos.length === 0) {\n      throw new Error(\"No images found on Pexels\");\n    }\n\n    const photo = data.photos[0];\n\n    const baseUrl = photo.src.original;\n    const sizeParams = new URLSearchParams();\n    sizeParams.append(\"auto\", \"compress\");\n    sizeParams.append(\"cs\", \"tinysrgb\"); // Default pexels param\n    if (options.width) sizeParams.append(\"w\", options.width.toString());\n    if (options.height) sizeParams.append(\"h\", options.height.toString());\n\n    const finalUrl = `${baseUrl}?${sizeParams.toString()}`;\n\n    return {\n      url: finalUrl,\n      width: options.width || photo.width,\n      height: options.height || photo.height,\n      author: photo.photographer,\n      authorUrl: photo.photographer_url,\n      originalUrl: photo.url,\n    };\n  }\n}\n","import axios from \"axios\";\nimport { ImageProvider, ImageOptions, ImageResult } from \"../types\";\n\nexport class PixabayProvider implements ImageProvider {\n  private apiKey: string;\n\n  constructor(apiKey: string) {\n    this.apiKey = apiKey;\n  }\n\n  async fetchRandomImage(options: ImageOptions): Promise<ImageResult> {\n    const params: any = {\n      key: this.apiKey,\n      q: options.query || \"\",\n      per_page: 20, // Fetch a few to pick randomly\n    };\n\n    if (options.orientation) {\n      params.orientation =\n        options.orientation === \"portrait\" ? \"vertical\" : \"horizontal\";\n    }\n\n    const response = await axios.get(\"https://pixabay.com/api/\", {\n      params,\n    });\n\n    const hits = response.data.hits;\n\n    if (!hits || hits.length === 0) {\n      throw new Error(\"No images found\");\n    }\n\n    // Pick a random hit\n    const randomHit = hits[Math.floor(Math.random() * hits.length)];\n\n    return {\n      url: randomHit.largeImageURL || randomHit.webformatURL,\n      width: randomHit.imageWidth || randomHit.webformatWidth,\n      height: randomHit.imageHeight || randomHit.webformatHeight,\n      author: randomHit.user,\n      authorUrl: `https://pixabay.com/users/${randomHit.user}-${randomHit.user_id}/`,\n      originalUrl: randomHit.pageURL,\n    };\n  }\n}\n","import { ImageProvider, ImageOptions, ImageResult, DownloadOptions } from './types';\nimport * as fs from 'fs';\nimport * as path from 'path';\nimport axios from 'axios';\nimport { v7 as uuidv4 } from 'uuid';\n\nexport class RandomImage {\n  private provider: ImageProvider;\n\n  constructor(provider: ImageProvider) {\n    this.provider = provider;\n  }\n\n  /**\n   * Fetches a random image based on the provided options.\n   * @param options - Configuration options for the image (width, height, query, etc.)\n   * @returns A promise that resolves to an ImageResult object.\n   */\n  async getRandom(options: ImageOptions = {}): Promise<ImageResult> {\n    return this.provider.fetchRandomImage(options);\n  }\n\n  /**\n   * Downloads an image to a specified directory.\n   * @param imageUrl - The URL of the image to download (can be a string or ImageResult object)\n   * @param destinationPath - The directory path where the image will be saved\n   * @param options - Download options (filename, overwrite, etc.)\n   * @returns A promise that resolves to the full path of the downloaded file\n   */\n  async download(\n    imageUrl: string | ImageResult,\n    destinationPath: string,\n    options: DownloadOptions = {}\n  ): Promise<string> {\n    const url = typeof imageUrl === 'string' ? imageUrl : imageUrl.url;\n\n    // Create directory if it doesn't exist\n    if (!fs.existsSync(destinationPath)) {\n      fs.mkdirSync(destinationPath, { recursive: true });\n    }\n\n    // Determine filename\n    let finalFilename: string;\n    if (options.filename) {\n      finalFilename = options.filename;\n    } else if (options.keepOriginalName) {\n      // keepOriginalName === true or undefined (default behavior: try to keep original)\n      const urlPath = new URL(url).pathname;\n      const urlFilename = path.basename(urlPath);\n      if (urlFilename && urlFilename.length > 0 && urlFilename !== '/') {\n        finalFilename = urlFilename;\n      } else {\n        // Fallback if no filename in URL\n        const ext = this.getExtensionFromUrl(url) || '.jpg';\n        finalFilename = `${uuidv4()}${ext}`;\n      }\n    } else {\n      // Generate UUID v4 filename\n      const ext = this.getExtensionFromUrl(url) || '.jpg';\n      finalFilename = `${uuidv4()}${ext}`;\n    }\n\n    // Ensure filename has an extension\n    if (!path.extname(finalFilename)) {\n      finalFilename += '.jpg';\n    }\n\n    const fullPath = path.join(destinationPath, finalFilename);\n\n    // Check if file exists and overwrite option\n    if (fs.existsSync(fullPath) && !options.overwrite) {\n      throw new Error(`File already exists: ${fullPath}. Set overwrite: true to replace it.`);\n    }\n\n    try {\n      const response = await axios.get(url, {\n        responseType: 'stream',\n        maxRedirects: 5, // Automatically handle redirects\n      });\n\n      const writer = fs.createWriteStream(fullPath);\n\n      response.data.pipe(writer);\n\n      return new Promise((resolve, reject) => {\n        writer.on('finish', () => {\n          resolve(fullPath);\n        });\n\n        writer.on('error', (err) => {\n          fs.unlink(fullPath, () => { }); // Delete partial file\n          reject(err);\n        });\n\n        response.data.on('error', (err: Error) => {\n          writer.close();\n          fs.unlink(fullPath, () => { }); // Delete partial file\n          reject(err);\n        });\n      });\n    } catch (error) {\n      if (axios.isAxiosError(error)) {\n        throw new Error(`Failed to download image: ${error.message}`);\n      }\n      throw error;\n    }\n  }\n\n  /**\n   * Helper method to extract file extension from URL\n   * @param url - The URL to extract extension from\n   * @returns The file extension (e.g., '.jpg', '.png') or null\n   */\n  private getExtensionFromUrl(url: string): string | null {\n    try {\n      const urlPath = new URL(url).pathname;\n      const ext = path.extname(urlPath);\n      return ext || null;\n    } catch {\n      return null;\n    }\n  }\n}\n"],"mappings":"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","names":["axios","axios","axios"]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nghiavuive/random-image",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",
@@ -31,8 +31,14 @@
   },
   "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",
+    "uuid": "^13.0.0"
   }
 }