mikes-php-image-handler 1.0.0 → 1.1.0

package/README.md

@@ -17,7 +17,9 @@ const fs = require('fs');
 // Initialize the client
 const imageClient = new VampireImageClient({
     baseUrl: 'https://img.miketsak.gr',
-    apiKey: 'your_api_key_here'
+    apiKey: 'your_api_key_here',
+    timeoutMs: 30000,   // Optional: Request timeout in ms (default: 30000)
+    maxRetries: 3       // Optional: Number of retries on network failure (default: 3)
 });
 
 async function run() {
@@ -33,7 +35,11 @@ async function run() {
         console.error('Upload failed:', uploadResult.error);
     }
 
-    // 2. Delete an Image
+    // 2. Upload a Base64 String
+    const base64Str = "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA...";
+    const base64Result = await imageClient.uploadBase64(base64Str, 'avatar.png');
+
+    // 3. Delete an Image
     if (uploadResult.success) {
         const deleteResult = await imageClient.deleteImage(uploadResult.filename);
         if (deleteResult.success) {
@@ -50,10 +56,17 @@ run();
 ### `new VampireImageClient(options)`
 - `options.baseUrl`: The URL of your PHP image API (e.g., `https://img.miketsak.gr`).
 - `options.apiKey`: The secret API key used for authentication.
+- `options.timeoutMs`: (Optional) The timeout in milliseconds before a request aborts. Default: `30000`.
+- `options.maxRetries`: (Optional) The number of automatic retries (with exponential backoff) for transient network failures. Default: `3`.
 
 ### `uploadImage(file, filename?)`
-- `file`: Can be a `Buffer`, a `Blob`, or a `File` object.
-- `filename`: Required if `file` is a Buffer. Represents the original name of the file (e.g., `avatar.png`).
+- `file`: Can be a `Buffer`, a `Uint8Array`, a `Blob`, or a `File` object.
+- `filename`: Required if `file` is a Buffer or Uint8Array. Represents the original name of the file (e.g., `avatar.png`).
+- **Returns**: A Promise resolving to an object `{ success: boolean, url?: string, filename?: string, error?: string }`.
+
+### `uploadBase64(base64String, filename)`
+- `base64String`: The Base64 string of the image. It handles stripping the `data:image/...;base64,` prefix automatically if present.
+- `filename`: The name to save the file as.
 - **Returns**: A Promise resolving to an object `{ success: boolean, url?: string, filename?: string, error?: string }`.
 
 ### `deleteImage(filename)`

package/dist/index.d.ts

@@ -1,29 +1,45 @@
 export interface VampireImageClientOptions {
     apiKey: string;
     baseUrl: string;
+    /** Default timeout in milliseconds for requests (default: 30000) */
+    timeoutMs?: number;
+    /** Maximum number of retries for failed network requests (default: 3) */
+    maxRetries?: number;
 }
 export interface UploadResponse {
-    success?: boolean;
+    success: boolean;
     url?: string;
     filename?: string;
     error?: string;
 }
 export interface DeleteResponse {
-    success?: boolean;
+    success: boolean;
     message?: string;
     error?: string;
 }
 export declare class VampireImageClient {
     private apiKey;
     private baseUrl;
+    private timeoutMs;
+    private maxRetries;
     constructor(options: VampireImageClientOptions);
     private getHeaders;
+    /**
+     * Internal fetch wrapper with timeout and retry logic
+     */
+    private fetchWithRetry;
     /**
      * Upload an image to the PHP server.
-     * @param file A standard File or Blob object (from browser)
-     * @param filename Optional filename (mainly for Node.js usage where Blob might not have a name)
+     * @param file A standard File, Blob, Buffer, or Uint8Array.
+     * @param filename Optional filename (required if passing a Buffer/Uint8Array)
+     */
+    uploadImage(file: Blob | Uint8Array, filename?: string): Promise<UploadResponse>;
+    /**
+     * Upload a Base64 encoded image string to the PHP server.
+     * @param base64String The base64 string (can include the data URI prefix like "data:image/png;base64,...")
+     * @param filename The filename to save it as
      */
-    uploadImage(file: Blob, filename?: string): Promise<UploadResponse>;
+    uploadBase64(base64String: string, filename: string): Promise<UploadResponse>;
     /**
      * Delete an image by its filename
      * @param filename The exact filename (e.g., 'img_123.jpg')

package/dist/index.js

@@ -4,9 +4,13 @@ exports.VampireImageClient = void 0;
 class VampireImageClient {
     apiKey;
     baseUrl;
+    timeoutMs;
+    maxRetries;
     constructor(options) {
         this.apiKey = options.apiKey;
         this.baseUrl = options.baseUrl.replace(/\/$/, '');
+        this.timeoutMs = options.timeoutMs || 30000;
+        this.maxRetries = options.maxRetries ?? 3;
     }
     getHeaders(isFormData = false) {
         const headers = {
@@ -17,58 +21,130 @@ class VampireImageClient {
         }
         return headers;
     }
+    /**
+     * Internal fetch wrapper with timeout and retry logic
+     */
+    async fetchWithRetry(url, options, retries) {
+        let lastError = new Error('Request failed');
+        for (let attempt = 0; attempt <= retries; attempt++) {
+            const controller = new AbortController();
+            const timeoutId = setTimeout(() => controller.abort(), this.timeoutMs);
+            try {
+                const res = await fetch(url, { ...options, signal: controller.signal });
+                clearTimeout(timeoutId);
+                if (res.ok || (res.status >= 400 && res.status < 500)) {
+                    // Successful response or client error (no need to retry 4xx errors usually)
+                    return res;
+                }
+                throw new Error(`Server responded with status ${res.status}`);
+            }
+            catch (err) {
+                clearTimeout(timeoutId);
+                lastError = err instanceof Error ? err : new Error(String(err));
+                // If it's an abort error (timeout), or network error, we retry.
+                if (attempt < retries) {
+                    const delay = Math.pow(2, attempt) * 1000; // Exponential backoff: 1s, 2s, 4s...
+                    await new Promise(resolve => setTimeout(resolve, delay));
+                }
+            }
+        }
+        throw lastError;
+    }
     /**
      * Upload an image to the PHP server.
-     * @param file A standard File or Blob object (from browser)
-     * @param filename Optional filename (mainly for Node.js usage where Blob might not have a name)
+     * @param file A standard File, Blob, Buffer, or Uint8Array.
+     * @param filename Optional filename (required if passing a Buffer/Uint8Array)
      */
     async uploadImage(file, filename) {
         const formData = new FormData();
+        let blobToUpload;
+        if (file instanceof Uint8Array) {
+            blobToUpload = new Blob([file]);
+        }
+        else {
+            blobToUpload = file;
+        }
         if (filename) {
-            formData.append('image', file, filename);
+            formData.append('image', blobToUpload, filename);
         }
         else {
-            formData.append('image', file);
+            formData.append('image', blobToUpload);
         }
         try {
-            const response = await fetch(`${this.baseUrl}/upload`, {
+            const response = await this.fetchWithRetry(`${this.baseUrl}/upload`, {
                 method: 'POST',
                 headers: this.getHeaders(true),
                 body: formData
-            });
+            }, this.maxRetries);
             if (!response.ok) {
                 const text = await response.text();
                 throw new Error(`Upload failed with status ${response.status}: ${text}`);
             }
             const data = await response.json();
-            return data;
+            return {
+                success: data.success || false,
+                url: data.url,
+                filename: data.filename,
+                error: data.error
+            };
         }
         catch (error) {
             return {
+                success: false,
                 error: error instanceof Error ? error.message : String(error)
             };
         }
     }
+    /**
+     * Upload a Base64 encoded image string to the PHP server.
+     * @param base64String The base64 string (can include the data URI prefix like "data:image/png;base64,...")
+     * @param filename The filename to save it as
+     */
+    async uploadBase64(base64String, filename) {
+        // Strip data prefix if present
+        const base64Data = base64String.replace(/^data:image\/\w+;base64,/, '');
+        try {
+            // Convert base64 to Uint8Array (works in Browser and Node)
+            const binaryString = atob(base64Data);
+            const len = binaryString.length;
+            const bytes = new Uint8Array(len);
+            for (let i = 0; i < len; i++) {
+                bytes[i] = binaryString.charCodeAt(i);
+            }
+            return await this.uploadImage(bytes, filename);
+        }
+        catch (error) {
+            return {
+                success: false,
+                error: `Failed to process base64 string: ${error instanceof Error ? error.message : String(error)}`
+            };
+        }
+    }
     /**
      * Delete an image by its filename
      * @param filename The exact filename (e.g., 'img_123.jpg')
      */
     async deleteImage(filename) {
         try {
-            const response = await fetch(`${this.baseUrl}/delete`, {
+            const response = await this.fetchWithRetry(`${this.baseUrl}/delete`, {
                 method: 'DELETE',
                 headers: this.getHeaders(),
                 body: JSON.stringify({ filename })
-            });
+            }, this.maxRetries);
             if (!response.ok) {
                 const text = await response.text();
                 throw new Error(`Delete failed with status ${response.status}: ${text}`);
             }
             const data = await response.json();
-            return data;
+            return {
+                success: data.success || false,
+                message: data.message,
+                error: data.error
+            };
         }
         catch (error) {
             return {
+                success: false,
                 error: error instanceof Error ? error.message : String(error)
             };
         }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mikes-php-image-handler",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "A Node.js client for uploading and managing images on a custom PHP image server.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/src/index.ts

@@ -1,17 +1,21 @@
 export interface VampireImageClientOptions {
     apiKey: string;
     baseUrl: string;
+    /** Default timeout in milliseconds for requests (default: 30000) */
+    timeoutMs?: number;
+    /** Maximum number of retries for failed network requests (default: 3) */
+    maxRetries?: number;
 }
 
 export interface UploadResponse {
-    success?: boolean;
+    success: boolean;
     url?: string;
     filename?: string;
     error?: string;
 }
 
 export interface DeleteResponse {
-    success?: boolean;
+    success: boolean;
     message?: string;
     error?: string;
 }
@@ -19,10 +23,14 @@ export interface DeleteResponse {
 export class VampireImageClient {
     private apiKey: string;
     private baseUrl: string;
+    private timeoutMs: number;
+    private maxRetries: number;
 
     constructor(options: VampireImageClientOptions) {
         this.apiKey = options.apiKey;
         this.baseUrl = options.baseUrl.replace(/\/$/, '');
+        this.timeoutMs = options.timeoutMs || 30000;
+        this.maxRetries = options.maxRetries ?? 3;
     }
 
     private getHeaders(isFormData = false): HeadersInit {
@@ -37,62 +45,143 @@ export class VampireImageClient {
         return headers;
     }
 
+    /**
+     * Internal fetch wrapper with timeout and retry logic
+     */
+    private async fetchWithRetry(url: string, options: RequestInit, retries: number): Promise<Response> {
+        let lastError: Error = new Error('Request failed');
+        
+        for (let attempt = 0; attempt <= retries; attempt++) {
+            const controller = new AbortController();
+            const timeoutId = setTimeout(() => controller.abort(), this.timeoutMs);
+            
+            try {
+                const res = await fetch(url, { ...options, signal: controller.signal });
+                clearTimeout(timeoutId);
+                
+                if (res.ok || (res.status >= 400 && res.status < 500)) {
+                    // Successful response or client error (no need to retry 4xx errors usually)
+                    return res;
+                }
+                
+                throw new Error(`Server responded with status ${res.status}`);
+            } catch (err) {
+                clearTimeout(timeoutId);
+                lastError = err instanceof Error ? err : new Error(String(err));
+                
+                // If it's an abort error (timeout), or network error, we retry.
+                if (attempt < retries) {
+                    const delay = Math.pow(2, attempt) * 1000; // Exponential backoff: 1s, 2s, 4s...
+                    await new Promise(resolve => setTimeout(resolve, delay));
+                }
+            }
+        }
+        
+        throw lastError;
+    }
+
     /**
      * Upload an image to the PHP server.
-     * @param file A standard File or Blob object (from browser)
-     * @param filename Optional filename (mainly for Node.js usage where Blob might not have a name)
+     * @param file A standard File, Blob, Buffer, or Uint8Array.
+     * @param filename Optional filename (required if passing a Buffer/Uint8Array)
      */
-    async uploadImage(file: Blob, filename?: string): Promise<UploadResponse> {
+    async uploadImage(file: Blob | Uint8Array, filename?: string): Promise<UploadResponse> {
         const formData = new FormData();
         
+        let blobToUpload: Blob;
+        
+        if (file instanceof Uint8Array) {
+            blobToUpload = new Blob([file as any]);
+        } else {
+            blobToUpload = file;
+        }
+
         if (filename) {
-            formData.append('image', file, filename);
+            formData.append('image', blobToUpload, filename);
         } else {
-            formData.append('image', file);
+            formData.append('image', blobToUpload);
         }
 
         try {
-            const response = await fetch(`${this.baseUrl}/upload`, {
+            const response = await this.fetchWithRetry(`${this.baseUrl}/upload`, {
                 method: 'POST',
                 headers: this.getHeaders(true),
                 body: formData
-            });
+            }, this.maxRetries);
 
             if (!response.ok) {
                 const text = await response.text();
                 throw new Error(`Upload failed with status ${response.status}: ${text}`);
             }
 
-            const data: UploadResponse = await response.json();
-            return data;
+            const data: any = await response.json();
+            return {
+                success: data.success || false,
+                url: data.url,
+                filename: data.filename,
+                error: data.error
+            };
         } catch (error) {
             return {
+                success: false,
                 error: error instanceof Error ? error.message : String(error)
             };
         }
     }
 
+    /**
+     * Upload a Base64 encoded image string to the PHP server.
+     * @param base64String The base64 string (can include the data URI prefix like "data:image/png;base64,...")
+     * @param filename The filename to save it as
+     */
+    async uploadBase64(base64String: string, filename: string): Promise<UploadResponse> {
+        // Strip data prefix if present
+        const base64Data = base64String.replace(/^data:image\/\w+;base64,/, '');
+        
+        try {
+            // Convert base64 to Uint8Array (works in Browser and Node)
+            const binaryString = atob(base64Data);
+            const len = binaryString.length;
+            const bytes = new Uint8Array(len);
+            for (let i = 0; i < len; i++) {
+                bytes[i] = binaryString.charCodeAt(i);
+            }
+            
+            return await this.uploadImage(bytes, filename);
+        } catch (error) {
+            return {
+                success: false,
+                error: `Failed to process base64 string: ${error instanceof Error ? error.message : String(error)}`
+            };
+        }
+    }
+
     /**
      * Delete an image by its filename
      * @param filename The exact filename (e.g., 'img_123.jpg')
      */
     async deleteImage(filename: string): Promise<DeleteResponse> {
         try {
-            const response = await fetch(`${this.baseUrl}/delete`, {
+            const response = await this.fetchWithRetry(`${this.baseUrl}/delete`, {
                 method: 'DELETE',
                 headers: this.getHeaders(),
                 body: JSON.stringify({ filename })
-            });
+            }, this.maxRetries);
 
             if (!response.ok) {
                 const text = await response.text();
                 throw new Error(`Delete failed with status ${response.status}: ${text}`);
             }
 
-            const data: DeleteResponse = await response.json();
-            return data;
+            const data: any = await response.json();
+            return {
+                success: data.success || false,
+                message: data.message,
+                error: data.error
+            };
         } catch (error) {
             return {
+                success: false,
                 error: error instanceof Error ? error.message : String(error)
             };
         }