txb-cloudinary-image-uploader 1.0.0 → 1.0.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "txb-cloudinary-image-uploader",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "description": "A lightweight, promise-based utility to handle seamless image uploads to Cloudinary directly from the browser.",
   "license": "ISC",
   "author": "Saleh Ahmed Mahin",

package/readme.md

@@ -1,63 +1,69 @@
 # Cloudinary Image Upload Utility
 
-A lightweight TypeScript utility function to handle image uploads directly from the client-side (browser) to Cloudinary using **Unsigned Uploads**. This utility uses the native `fetch` API, eliminating the need for heavy external libraries like Axios.
+A lightweight, type-safe TypeScript utility for handling direct client-side image uploads to Cloudinary using **Unsigned Uploads**. This implementation leverages the native `fetch` API, keeping your bundle size small by avoiding external dependencies like Axios.
 
 ## Table of Contents
 * [Features](#features)
 * [Prerequisites](#prerequisites)
-* [Installation](#installation)
-* [Usage](#usage)
+* [The Utility Function](#the-utility-function)
+* [Usage Example (React)](#usage-example-react)
 * [Response Structure](#response-structure)
 
 ## Features
-- **Simple Integration**: Upload images with a single function call.
-- **TypeScript Support**: Fully typed interface for predictable data structures and better DX.
-- **Detailed Error Handling**: Log detailed error data to the console if the upload fails.
-- **Lightweight**: Built with the native Fetch API—no extra dependencies required.
+- **Zero Dependencies**: Uses the native Fetch API.
+- **Type Safety**: Fully typed interface for predictable data structures and better DX.
+- **Error Handling**: Captures and logs detailed Cloudinary API responses.
+- **Lightweight**: Optimized for modern browser environments.
 
 ## Prerequisites
-Before using this function, gather the following details from your Cloudinary Dashboard:
+Before using this function, gather the following details from your [Cloudinary Dashboard](https://cloudinary.com/console):
 1. **Cloud Name**: Your unique Cloudinary identifier.
 2. **Upload Preset**: Create an **'Unsigned'** upload preset in Cloudinary Settings (Settings > Upload).
-3. **Cloudinary URL**: Typically formatted as: `https://api.cloudinary.com/v1_1/YOUR_CLOUD_NAME`
-
-## Installation
-Create a file named `cloudinary.ts` inside your project's `utils` or `lib` folder and paste the function code there.
-
-```bash
-# No additional packages are required.
-
-### React Example
-```
-import { uploadToCloudinary } from './utils/cloudinary';
-
-const ImageUploadComponent = () => {
-  const handleFileChange = async (event: React.ChangeEvent<HTMLInputElement>) => {
-    const file = event.target.files?.[0];
-    if (!file) return;
-
-    // Use environment variables for production security
-    const CLOUDINARY_URL = "[https://api.cloudinary.com/v1_1/your_cloud_name](https://api.cloudinary.com/v1_1/your_cloud_name)";
-    const UPLOAD_PRESET = "your_unsigned_preset";
-
-    try {
-      const response = await uploadToCloudinary(file, UPLOAD_PRESET, CLOUDINARY_URL);
-      
-      console.log("Uploaded URL:", response.url);
-      console.log("Public ID:", response.public_id);
-      
-      alert("Upload Successful!");
-    } catch (error) {
-      console.error("Upload failed:", error);
-      alert("Failed to upload image. Please check the console for details.");
-    }
-  };
-
-  return (
-    <div>
-      <label>Choose an image:</label>
-      <input type="file" onChange={handleFileChange} />
-    </div>
-  );
-};
-```
+3. **API URL**: Typically formatted as: `https://api.cloudinary.com/v1_1/YOUR_CLOUD_NAME/image/upload`
+
+---
+
+## The Utility Function
+
+Create a file named `cloudinary.ts` inside your project's `utils` or `lib` folder.
+
+```typescript
+export interface CloudinaryResponse {
+  public_id: string;
+  version: number;
+  width: number;
+  height: number;
+  format: string;
+  resource_type: string;
+  created_at: string;
+  bytes: number;
+  type: string;
+  url: string;
+  secure_url: string;
+  [key: string]: any; // Catch-all for additional metadata
+}
+
+/**
+ * Uploads a file to Cloudinary using Unsigned Uploads.
+ */
+export const uploadToCloudinary = async (
+  file: File,
+  uploadPreset: string,
+  cloudinaryUrl: string
+): Promise<CloudinaryResponse> => {
+  const formData = new FormData();
+  formData.append("file", file);
+  formData.append("upload_preset", uploadPreset);
+
+  const response = await fetch(cloudinaryUrl, {
+    method: "POST",
+    body: formData,
+  });
+
+  if (!response.ok) {
+    const errorData = await response.json();
+    throw new Error(errorData.error?.message || "Failed to upload image");
+  }
+
+  return response.json();
+};