@fractalq/client 2.1.1

package/src/storage/firebase/upload-task.js

@@ -0,0 +1,31 @@
+import { ref, uploadBytesResumable, getDownloadURL } from 'firebase/storage';
+
+/**
+ * Run resumable upload with optional progress callback (0–1).
+ */
+export function runResumableUpload(storageInstance, path, fileName, blob, onProgress) {
+  const storageRef = ref(storageInstance, `${path}/${fileName}`);
+  return new Promise((resolve, reject) => {
+    const uploadTask = uploadBytesResumable(storageRef, blob);
+    uploadTask.on(
+      'state_changed',
+      (snapshot) => {
+        if (onProgress) {
+          onProgress(snapshot.bytesTransferred / snapshot.totalBytes);
+        }
+      },
+      (error) => {
+        console.error('Firebase upload error:', error);
+        reject(new Error(`Firebase upload failed: ${error.message}`));
+      },
+      async () => {
+        try {
+          const downloadURL = await getDownloadURL(uploadTask.snapshot.ref);
+          resolve(downloadURL);
+        } catch (error) {
+          reject(new Error(`Failed to get download URL: ${error.message}`));
+        }
+      }
+    );
+  });
+}

package/src/storage/firebase/upload-to-firebase.js

@@ -0,0 +1,33 @@
+import { getStorageInstance } from './instance.js';
+import { imageDataToBlob } from './image-to-blob.js';
+import { runResumableUpload } from './upload-task.js';
+
+export async function uploadToFirebase({
+  imageData,
+  path,
+  fileName,
+  onProgress,
+  firebaseStorage,
+  firebaseConfig,
+}) {
+  try {
+    const storageInstance = getStorageInstance({ firebaseStorage, firebaseConfig });
+    if (!storageInstance) {
+      throw new Error('Firebase Storage is not initialized. Provide firebaseStorage or firebaseConfig in options.');
+    }
+    const blob = await imageDataToBlob(imageData);
+    return runResumableUpload(storageInstance, path, fileName, blob, onProgress);
+  } catch (error) {
+    console.error('uploadToFirebase error:', error);
+    throw error;
+  }
+}
+
+export async function uploadFileToFirebase(file, path, onProgress = null) {
+  return uploadToFirebase({
+    imageData: file,
+    path,
+    fileName: file.name,
+    onProgress,
+  });
+}

package/src/storage/shared/base64-data-url-to-blob.js

@@ -0,0 +1,24 @@
+/**
+ * Parse a data URL into a Blob (browser).
+ */
+export function base64DataUrlToBlob(base64String) {
+  return new Promise((resolve, reject) => {
+    try {
+      const matches = base64String.match(/^data:([A-Za-z-+\/]+);base64,(.+)$/);
+      if (!matches || matches.length !== 3) {
+        throw new Error('Invalid base64 string format');
+      }
+      const mimeType = matches[1];
+      const base64Data = matches[2];
+      const byteCharacters = atob(base64Data);
+      const byteNumbers = new Array(byteCharacters.length);
+      for (let i = 0; i < byteCharacters.length; i++) {
+        byteNumbers[i] = byteCharacters.charCodeAt(i);
+      }
+      const byteArray = new Uint8Array(byteNumbers);
+      resolve(new Blob([byteArray], { type: mimeType }));
+    } catch (error) {
+      reject(error);
+    }
+  });
+}

package/src/storage/temp/TempFileManager.js

@@ -0,0 +1,102 @@
+/**
+ * Temporary file storage keyed by job id (Firebase Storage).
+ */
+
+import { ref, deleteObject } from 'firebase/storage';
+import { uploadBlobToTempPath } from './upload-core.js';
+
+export class TempFileManager {
+  constructor(storageInstance, options = {}) {
+    if (!storageInstance) {
+      throw new Error('Firebase Storage instance is required');
+    }
+    this.storage = storageInstance;
+    this.tempPathPrefix = options.tempPathPrefix || 'temp/fractalq';
+    this.autoCleanup = options.autoCleanup !== false;
+    /** @type {Map<string, string[]>} */
+    this.trackedFiles = new Map();
+  }
+
+  async uploadTempFile(fileData, jobId, fileName = null, onProgress = null) {
+    if (!jobId) {
+      throw new Error('Job ID is required for temporary file management');
+    }
+    return uploadBlobToTempPath({
+      storage: this.storage,
+      tempPathPrefix: this.tempPathPrefix,
+      jobId,
+      fileName,
+      fileData,
+      onProgress,
+      trackFile: (id, path) => this.trackFile(id, path),
+    });
+  }
+
+  trackFile(jobId, filePath) {
+    if (!this.trackedFiles.has(jobId)) {
+      this.trackedFiles.set(jobId, []);
+    }
+    this.trackedFiles.get(jobId).push(filePath);
+  }
+
+  async cleanupJob(jobId) {
+    if (!this.trackedFiles.has(jobId)) {
+      console.log(`ℹ️ No files tracked for job: ${jobId}`);
+      return { deleted: 0, errors: 0 };
+    }
+    const filePaths = this.trackedFiles.get(jobId);
+    let deleted = 0;
+    let errors = 0;
+    console.log(`🧹 Cleaning up ${filePaths.length} temporary files for job: ${jobId}`);
+
+    for (const filePath of filePaths) {
+      try {
+        const fileRef = ref(this.storage, filePath);
+        await deleteObject(fileRef);
+        deleted++;
+        console.log(`✅ Deleted temporary file: ${filePath}`);
+      } catch (error) {
+        if (error.code !== 'storage/object-not-found') {
+          console.error(`❌ Failed to delete ${filePath}:`, error.message);
+          errors++;
+        } else {
+          deleted++;
+        }
+      }
+    }
+
+    try {
+      ref(this.storage, `${this.tempPathPrefix}/${jobId}`);
+    } catch (_) {}
+
+    this.trackedFiles.delete(jobId);
+    console.log(`✅ Cleanup complete for job ${jobId}: ${deleted} deleted, ${errors} errors`);
+    return { deleted, errors };
+  }
+
+  async deleteFile(filePath) {
+    try {
+      const fileRef = ref(this.storage, filePath);
+      await deleteObject(fileRef);
+      console.log(`✅ Deleted file: ${filePath}`);
+      return true;
+    } catch (error) {
+      if (error.code === 'storage/object-not-found') {
+        console.log(`ℹ️ File already deleted: ${filePath}`);
+        return true;
+      }
+      console.error(`❌ Failed to delete ${filePath}:`, error.message);
+      return false;
+    }
+  }
+
+  getTrackedFiles(jobId) {
+    return this.trackedFiles.get(jobId) || [];
+  }
+
+  clearTracking(jobId) {
+    this.trackedFiles.delete(jobId);
+  }
+}
+
+export default TempFileManager;

package/src/storage/temp/generate-filename.js

@@ -0,0 +1,22 @@
+import { MIME_TO_EXT } from './mime-extension-map.js';
+
+/**
+ * Infer extension from fileData; build unique name under job folder.
+ */
+export function generateTempFileName(fileData) {
+  const timestamp = Date.now();
+  const random = Math.random().toString(36).substring(2, 9);
+  let ext = 'bin';
+  if (fileData instanceof File) {
+    ext = fileData.name.split('.').pop() || 'bin';
+  } else if (fileData instanceof Blob) {
+    ext = fileData.type.split('/').pop() || 'bin';
+  } else if (typeof fileData === 'string' && fileData.startsWith('data:')) {
+    const mimeMatch = fileData.match(/^data:([^;]+)/);
+    if (mimeMatch) {
+      const mimeType = mimeMatch[1];
+      ext = MIME_TO_EXT[mimeType] || mimeType.split('/').pop() || 'bin';
+    }
+  }
+  return `${timestamp}_${random}.${ext}`;
+}

package/src/storage/temp/index.js

@@ -0,0 +1,2 @@
+export { TempFileManager } from './TempFileManager.js';
+export { default } from './TempFileManager.js';

package/src/storage/temp/input-to-blob.js

@@ -0,0 +1,18 @@
+import { base64DataUrlToBlob } from '../shared/base64-data-url-to-blob.js';
+
+export async function tempInputToBlob(fileData) {
+  if (fileData instanceof Blob || fileData instanceof File) {
+    return fileData;
+  }
+  if (typeof fileData === 'string') {
+    if (fileData.startsWith('data:')) {
+      return base64DataUrlToBlob(fileData);
+    }
+    if (fileData.startsWith('http://') || fileData.startsWith('https://')) {
+      const response = await fetch(fileData);
+      return response.blob();
+    }
+    return base64DataUrlToBlob(`data:application/octet-stream;base64,${fileData}`);
+  }
+  throw new Error('Invalid file data format');
+}

package/src/storage/temp/mime-extension-map.js

@@ -0,0 +1,12 @@
+/** Map data-URL / MIME hints to file extensions for temp uploads. */
+export const MIME_TO_EXT = {
+  'image/jpeg': 'jpg',
+  'image/jpg': 'jpg',
+  'image/png': 'png',
+  'image/gif': 'gif',
+  'image/webp': 'webp',
+  'video/mp4': 'mp4',
+  'video/webm': 'webm',
+  'model/gltf-binary': 'glb',
+  'model/gltf+json': 'gltf',
+};

package/src/storage/temp/upload-core.js

@@ -0,0 +1,49 @@
+import { ref, uploadBytesResumable, getDownloadURL } from 'firebase/storage';
+import { generateTempFileName } from './generate-filename.js';
+import { tempInputToBlob } from './input-to-blob.js';
+
+export async function uploadBlobToTempPath({
+  storage,
+  tempPathPrefix,
+  jobId,
+  fileName,
+  fileData,
+  onProgress,
+  trackFile,
+}) {
+  const resolvedName = fileName || generateTempFileName(fileData);
+  const tempPath = `${tempPathPrefix}/${jobId}/${resolvedName}`;
+  const storageRef = ref(storage, tempPath);
+  const blob = await tempInputToBlob(fileData);
+
+  return new Promise((resolve, reject) => {
+    const uploadTask = uploadBytesResumable(storageRef, blob);
+    uploadTask.on(
+      'state_changed',
+      (snapshot) => {
+        if (onProgress) {
+          onProgress(snapshot.bytesTransferred / snapshot.totalBytes);
+        }
+      },
+      (error) => {
+        console.error('Temp file upload error:', error);
+        reject(new Error(`Failed to upload temporary file: ${error.message}`));
+      },
+      async () => {
+        try {
+          const downloadURL = await getDownloadURL(uploadTask.snapshot.ref);
+          trackFile(jobId, tempPath);
+          console.log(`✅ Temporary file uploaded: ${tempPath}`);
+          resolve({
+            url: downloadURL,
+            path: tempPath,
+            fileName: resolvedName,
+            jobId,
+          });
+        } catch (error) {
+          reject(new Error(`Failed to get download URL: ${error.message}`));
+        }
+      }
+    );
+  });
+}

package/useFractalQ.d.ts

@@ -0,0 +1,29 @@
+import type {
+  ExecuteNodeOptions,
+  FractalQ,
+  FractalQClientOptions,
+  FractalQResponse,
+} from './index.js';
+
+export function useFractalQ(options?: FractalQClientOptions): {
+  client: FractalQ;
+  executeNode: (
+    nodeId: string | null,
+    inputs?: Record<string, unknown>,
+    executeOptions?: ExecuteNodeOptions
+  ) => Promise<FractalQResponse>;
+  upscaleAndUpload: (
+    image: File | Blob | string,
+    uploadOptions?: Record<string, unknown>
+  ) => Promise<string | Record<string, unknown>>;
+  executePipeline: (
+    nodePipeline: Array<Record<string, unknown>>,
+    pipelineOptions?: Record<string, unknown>
+  ) => Promise<{ success: boolean; data?: unknown }>;
+  loading: boolean;
+  error: string | null;
+  progress: unknown;
+  reset: () => void;
+};
+
+export default useFractalQ;

package/useFractalQ.js

@@ -0,0 +1,126 @@
+/**
+ * React Hook for FractalQ Client
+ * 
+ * Provides a convenient hook for using FractalQ in React components
+ */
+
+import { useState, useCallback, useRef } from 'react';
+import FractalQ from './index.js';
+
+/**
+ * React hook for FractalQ API
+ * @param {Object} options - Client options
+ * @returns {Object} Hook interface
+ */
+export function useFractalQ(options = {}) {
+  const [loading, setLoading] = useState(false);
+  const [error, setError] = useState(null);
+  const [progress, setProgress] = useState(null);
+  
+  // Create client instance (reuse if options don't change)
+  const clientRef = useRef(null);
+  if (!clientRef.current) {
+    clientRef.current = new FractalQ(options);
+  }
+
+  /**
+   * Execute a node
+   */
+  const executeNode = useCallback(async (nodeId, inputs = {}, executeOptions = {}) => {
+    setLoading(true);
+    setError(null);
+    setProgress(null);
+
+    try {
+      const result = await clientRef.current.execute(nodeId, inputs, executeOptions);
+      setLoading(false);
+      return result;
+    } catch (err) {
+      setError(err.message);
+      setLoading(false);
+      throw err;
+    }
+  }, []);
+
+  /**
+   * Upscale and upload image
+   */
+  const upscaleAndUpload = useCallback(async (image, uploadOptions = {}) => {
+    setLoading(true);
+    setError(null);
+    setProgress({ step: 'initializing', progress: 0 });
+
+    try {
+      const url = await clientRef.current.upscaleAndUpload(image, {
+        ...uploadOptions,
+        onProgress: (progressInfo) => {
+          setProgress(progressInfo);
+          if (uploadOptions.onProgress) {
+            uploadOptions.onProgress(progressInfo);
+          }
+        },
+      });
+      
+      setLoading(false);
+      setProgress({ step: 'complete', progress: 1 });
+      return url;
+    } catch (err) {
+      setError(err.message);
+      setLoading(false);
+      setProgress(null);
+      throw err;
+    }
+  }, []);
+
+  /**
+   * Execute pipeline
+   */
+  const executePipeline = useCallback(async (nodePipeline, pipelineOptions = {}) => {
+    setLoading(true);
+    setError(null);
+    setProgress(null);
+
+    try {
+      const result = await clientRef.current.executePipeline(nodePipeline, {
+        ...pipelineOptions,
+        onProgress: (progressInfo) => {
+          setProgress(progressInfo);
+          if (pipelineOptions.onProgress) {
+            pipelineOptions.onProgress(progressInfo);
+          }
+        },
+      });
+      
+      setLoading(false);
+      return result;
+    } catch (err) {
+      setError(err.message);
+      setLoading(false);
+      setProgress(null);
+      throw err;
+    }
+  }, []);
+
+  /**
+   * Reset state
+   */
+  const reset = useCallback(() => {
+    setLoading(false);
+    setError(null);
+    setProgress(null);
+  }, []);
+
+  return {
+    client: clientRef.current,
+    executeNode,
+    upscaleAndUpload,
+    executePipeline,
+    loading,
+    error,
+    progress,
+    reset,
+  };
+}
+
+export default useFractalQ;
+