@fractalq/client 2.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) FractalQ
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,55 @@
+# @fractalq/client
+
+JavaScript client for [FractalQ](https://fractalq.com). **API keys are never read from environment variables inside this package** — pass them from your app (DB, vault, or your own `process.env` in application code).
+
+## Install
+
+```bash
+npm install @fractalq/client
+```
+
+## Config (server)
+
+```js
+import { getSignalQApiUrl, getFractalQApiKey } from '@fractalq/client';
+
+const key = process.env.MY_APP_FRACTALQ_NODE_KEY; // your app loads this, not the library
+const url = getSignalQApiUrl(getFractalQApiKey(key));
+```
+
+## Browser (proxy + Firebase token)
+
+```js
+import FractalQ from '@fractalq/client';
+
+const client = new FractalQ({
+  useBackendProxy: true,
+  sessionApiKey: nodeKeyFromYourUi,
+  authTokenProvider: async () => {
+    const user = getFirebaseAuth().currentUser;
+    return user ? user.getIdToken() : null;
+  },
+});
+
+await client.execute(null, { input_0: imageUrl }, { async: true, callbackUrl, memeId });
+```
+
+## Publish
+
+```bash
+cd fractalq-client
+npm login
+npm publish --access public
+```
+
+Scoped package `@fractalq/client` requires npm org access or publish under your scope.
+
+## Local link (monorepo)
+
+In WOKENMEME `package.json`:
+
+```json
+"@fractalq/client": "file:../fractalq-client"
+```
+
+Then `yarn` or `npm install`.

package/examples/async-callback.js

@@ -0,0 +1,88 @@
+/**
+ * Async Processing with Callback Example
+ * 
+ * Example showing how to use async processing with webhook callbacks
+ * for long-running operations
+ */
+
+import FractalQ from '@fractalq/client';
+import express from 'express';
+
+const fractalq = new FractalQ({
+  apiKey: process.env.FRACTALQ_API_KEY
+});
+
+// Setup Express server to receive callbacks
+const app = express();
+app.use(express.json());
+
+// Webhook endpoint to receive processing results
+app.post('/webhook/fractalq-callback', (req, res) => {
+  const { success, data, jobId, error } = req.body;
+
+  console.log('Received callback for job:', jobId);
+
+  if (success) {
+    console.log('Processing complete!');
+    console.log('Result:', data.output_0);
+    
+    // Handle the result (save to database, notify user, etc.)
+    handleProcessingComplete(jobId, data);
+  } else {
+    console.error('Processing failed:', error);
+    handleProcessingError(jobId, error);
+  }
+
+  res.status(200).json({ received: true });
+});
+
+// Start async processing
+async function startAsyncProcessing(imageFile, userId) {
+  try {
+    // Start processing with callback URL
+    const result = await fractalq.execute('heavy_processing_node', {
+      input_0: imageFile,
+      user_id: userId
+    }, {
+      callbackUrl: 'https://yourapp.com/webhook/fractalq-callback'
+    });
+
+    console.log('Processing started');
+    console.log('Job ID:', result.jobId);
+
+    // Store job ID in database for tracking
+    await saveJobToDatabase(userId, result.jobId);
+
+    return result.jobId;
+  } catch (error) {
+    console.error('Failed to start processing:', error);
+    throw error;
+  }
+}
+
+function handleProcessingComplete(jobId, data) {
+  // Implement your logic here
+  console.log(`Job ${jobId} completed successfully`);
+  // Update database, send notification, etc.
+}
+
+function handleProcessingError(jobId, error) {
+  // Implement your error handling here
+  console.log(`Job ${jobId} failed:`, error);
+  // Update database, notify user of failure, etc.
+}
+
+async function saveJobToDatabase(userId, jobId) {
+  // Implement your database logic
+  console.log(`Saving job ${jobId} for user ${userId}`);
+}
+
+// Start server
+const PORT = process.env.PORT || 3000;
+app.listen(PORT, () => {
+  console.log(`Webhook server listening on port ${PORT}`);
+});
+
+// Example usage
+// startAsyncProcessing(imageFile, 'user123');
+

package/examples/basic-usage.js

@@ -0,0 +1,29 @@
+/**
+ * Basic Usage Example
+ * 
+ * Simple example showing how to initialize and use the FractalQ client
+ */
+
+import FractalQ from '@fractalq/client';
+
+// Load the key in YOUR app (env / DB / vault). @fractalq/client does not read env for secrets.
+const nodeApiKey = process.env.FRACTALQ_API_KEY;
+if (!nodeApiKey) throw new Error('Set FRACTALQ_API_KEY on the host; never commit keys to git or npm.');
+const fractalq = new FractalQ({ apiKey: nodeApiKey });
+
+async function basicExample() {
+  try {
+    // Execute a node
+    const result = await fractalq.execute('your_node_id', {
+      input_0: 'https://example.com/image.jpg'
+    });
+
+    console.log('Success!', result.data);
+    console.log('Output:', result.data.output_0);
+  } catch (error) {
+    console.error('Error:', error.message);
+  }
+}
+
+basicExample();
+

package/examples/image-upscaling.js

@@ -0,0 +1,48 @@
+/**
+ * Image Upscaling Example
+ * 
+ * Example showing how to upscale images with Firebase upload
+ */
+
+import FractalQ from '@fractalq/client';
+import { initializeApp } from 'firebase/app';
+import { getStorage } from 'firebase/storage';
+
+// Initialize Firebase
+const app = initializeApp({
+  apiKey: process.env.FIREBASE_API_KEY,
+  authDomain: process.env.FIREBASE_AUTH_DOMAIN,
+  projectId: process.env.FIREBASE_PROJECT_ID,
+  storageBucket: process.env.FIREBASE_STORAGE_BUCKET,
+});
+
+const storage = getStorage(app);
+
+// Initialize FractalQ with Firebase
+const fractalq = new FractalQ({
+  apiKey: process.env.FRACTALQ_API_KEY,
+  firebaseStorage: storage
+});
+
+async function upscaleImage(imageFile) {
+  try {
+    // Upscale and upload in one step
+    const uploadedUrl = await fractalq.upscaleAndUpload(imageFile, {
+      uploadPath: 'images/upscaled',
+      fileName: 'result.jpg',
+      onProgress: (progress) => {
+        console.log(`${progress.step}: ${progress.progress}%`);
+      }
+    });
+
+    console.log('Upscaled image URL:', uploadedUrl);
+    return uploadedUrl;
+  } catch (error) {
+    console.error('Upscaling failed:', error);
+    throw error;
+  }
+}
+
+// Example usage
+// upscaleImage(myImageFile);
+

package/examples/pipeline-processing.js

@@ -0,0 +1,51 @@
+/**
+ * Pipeline Processing Example
+ * 
+ * Example showing how to chain multiple AI operations
+ */
+
+import FractalQ from '@fractalq/client';
+
+const fractalq = new FractalQ({
+  apiKey: process.env.FRACTALQ_API_KEY
+});
+
+async function processImagePipeline(imageFile) {
+  try {
+    // Define processing pipeline
+    const result = await fractalq.executePipeline([
+      {
+        nodeId: 'upscale_2x',
+        inputs: { quality: 'high' }
+      },
+      {
+        nodeId: 'enhance_colors',
+        transform: (data) => ({
+          // Transform data between steps if needed
+          input_0: data.output_0
+        })
+      },
+      {
+        nodeId: 'apply_filter',
+        inputs: { filterType: 'sharpen', strength: 0.8 }
+      }
+    ], {
+      initialData: { input_0: imageFile },
+      onProgress: ({ step, progress, nodeId }) => {
+        console.log(`Processing ${nodeId}: ${progress}%`);
+      }
+    });
+
+    console.log('Pipeline complete!');
+    console.log('Final result:', result.data.output_0);
+    
+    return result.data;
+  } catch (error) {
+    console.error('Pipeline failed:', error);
+    throw error;
+  }
+}
+
+// Example usage
+// processImagePipeline(myImageFile);
+

package/examples/react-component.jsx

@@ -0,0 +1,97 @@
+/**
+ * React Component Example
+ * 
+ * Example showing how to use FractalQ in a React component
+ */
+
+import React, { useState } from 'react';
+import { useFractalQ } from '@fractalq/client/useFractalQ';
+
+function ImageProcessor() {
+  const [selectedImage, setSelectedImage] = useState(null);
+  const [processedImage, setProcessedImage] = useState(null);
+  
+  const { execute, loading, error, reset } = useFractalQ({
+    apiKey: process.env.NEXT_PUBLIC_FRACTALQ_API_KEY
+  });
+
+  const handleFileChange = (event) => {
+    const file = event.target.files[0];
+    if (file) {
+      setSelectedImage(file);
+      setProcessedImage(null);
+      reset();
+    }
+  };
+
+  const handleProcess = async () => {
+    if (!selectedImage) return;
+
+    try {
+      const result = await execute('upscale_node_id', {
+        input_0: selectedImage
+      });
+
+      setProcessedImage(result.data.output_0);
+    } catch (err) {
+      console.error('Processing failed:', err);
+    }
+  };
+
+  return (
+    <div className="image-processor">
+      <h2>Image Upscaler</h2>
+      
+      <div className="upload-section">
+        <input 
+          type="file" 
+          accept="image/*"
+          onChange={handleFileChange}
+          disabled={loading}
+        />
+      </div>
+
+      {selectedImage && (
+        <div className="preview">
+          <h3>Original Image</h3>
+          <img 
+            src={URL.createObjectURL(selectedImage)} 
+            alt="Original"
+            style={{ maxWidth: '400px' }}
+          />
+        </div>
+      )}
+
+      <button 
+        onClick={handleProcess}
+        disabled={!selectedImage || loading}
+        className="process-button"
+      >
+        {loading ? 'Processing...' : 'Upscale Image'}
+      </button>
+
+      {error && (
+        <div className="error-message">
+          Error: {error.message}
+        </div>
+      )}
+
+      {processedImage && (
+        <div className="result">
+          <h3>Processed Image</h3>
+          <img 
+            src={processedImage} 
+            alt="Processed"
+            style={{ maxWidth: '800px' }}
+          />
+          <a href={processedImage} download>
+            Download Result
+          </a>
+        </div>
+      )}
+    </div>
+  );
+}
+
+export default ImageProcessor;
+

package/examples/smoke-config.mjs

@@ -0,0 +1,26 @@
+/**
+ * Local smoke test (no secrets). Run from fractalq-client/: npm run test:smoke
+ */
+import { getSignalQBaseUrl, getFractalQApiKey, getSignalQApiUrl } from '../src/config/index.js';
+
+const base = getSignalQBaseUrl();
+if (base !== 'https://fractalq.com' && !base.startsWith('http')) {
+  console.error('FAIL: getSignalQBaseUrl');
+  process.exit(1);
+}
+
+try {
+  getFractalQApiKey('');
+  console.error('FAIL: getFractalQApiKey should throw on empty');
+  process.exit(1);
+} catch (_) {
+  // expected
+}
+
+const url = getSignalQApiUrl('testkey123');
+if (!url.includes('/api/node/api/testkey123/execute')) {
+  console.error('FAIL: getSignalQApiUrl', url);
+  process.exit(1);
+}
+
+console.log('OK @fractalq/client config smoke');

package/index.d.ts

@@ -0,0 +1,81 @@
+export interface FractalQClientOptions {
+  useBackendProxy?: boolean;
+  apiKey?: string;
+  nodeServiceApiKey?: string;
+  sessionApiKey?: string;
+  /**
+   * Proxy mode: optional; defaults to `/api/fractalq`.
+   * Direct mode (`useBackendProxy: false`): required unless the host sets `FRACTALQ_NODE_BASE_URL`
+   * or `NEXT_PUBLIC_FRACTALQ_BASE_URL`. The library does not embed a default API host.
+   */
+  baseUrl?: string;
+  timeout?: number;
+  firebaseStorage?: unknown;
+  firebaseConfig?: unknown;
+  authTokenProvider?: () => Promise<string | null | undefined>;
+}
+
+export function getSignalQBaseUrl(override?: string): string;
+export function getFractalQApiKey(apiKey: string): string;
+export function getSignalQApiUrl(apiKey: string, baseUrl?: string): string;
+export function getApiKeyBySessionId(
+  sessionId: string,
+  opts?: { accountApiKey?: string; baseUrl?: string }
+): Promise<string>;
+export function getSignalQApiUrlBySessionId(
+  sessionId: string,
+  opts?: { accountApiKey?: string; baseUrl?: string }
+): Promise<string>;
+
+export interface ExecuteNodeOptions {
+  timeout?: number;
+  callbackUrl?: string;
+  async?: boolean;
+  /**
+   * Optional label for this call before the server responds (e.g. temp file namespaces).
+   * The authoritative job id comes from FractalQ in `FractalQResponse.jobId` and in callbacks.
+   */
+  jobId?: string;
+  sessionApiKey?: string;
+  fractalqVersion?: string;
+  useTempFiles?: boolean;
+  onProgress?: (p: unknown) => void;
+  [key: string]: unknown;
+}
+
+export interface FractalQResponse {
+  success: boolean;
+  async?: boolean;
+  /** Job / request id issued by FractalQ (SignalQ) for tracking this run. */
+  jobId?: string;
+  message?: string;
+  data?: Record<string, unknown>;
+  error?: string;
+}
+
+export class FractalQClient {
+  constructor(options?: FractalQClientOptions);
+  execute(
+    nodeId: string | null,
+    inputs?: Record<string, unknown>,
+    options?: ExecuteNodeOptions
+  ): Promise<FractalQResponse>;
+  executeNode(
+    nodeId: string | null,
+    inputs?: Record<string, unknown>,
+    options?: ExecuteNodeOptions
+  ): Promise<FractalQResponse>;
+}
+
+export class FractalQ extends FractalQClient {
+  upscaleAndUpload(
+    image: File | Blob | string,
+    options?: Record<string, unknown>
+  ): Promise<string | Record<string, unknown>>;
+  executePipeline(
+    nodePipeline: Array<Record<string, unknown>>,
+    options?: Record<string, unknown>
+  ): Promise<{ success: boolean; data?: unknown }>;
+}
+
+export default FractalQ;

package/index.js

@@ -0,0 +1,45 @@
+/**
+ * @fractalq/client — public API (implementation lives under src/**).
+ */
+import FractalQClient from './src/client/FractalQClient.js';
+import PipelineProcessor from './src/pipeline/index.js';
+
+export { FractalQClient };
+
+export class FractalQ extends FractalQClient {
+  constructor(options = {}) {
+    super(options);
+    /** @type {import('./src/image/ImageProcessor.js').ImageProcessor | null} */
+    this._imageProcessor = null;
+    this._pipelineProcessor = new PipelineProcessor(this);
+  }
+
+  async _ensureImageProcessor() {
+    if (!this._imageProcessor) {
+      const { ImageProcessor } = await import('./src/image/index.js');
+      this._imageProcessor = new ImageProcessor(this);
+    }
+    return this._imageProcessor;
+  }
+
+  async upscaleAndUpload(image, options = {}) {
+    const ip = await this._ensureImageProcessor();
+    return ip.upscaleAndUpload(image, options);
+  }
+
+  executePipeline(nodePipeline, options = {}) {
+    return this._pipelineProcessor.execute(nodePipeline, options);
+  }
+}
+
+export {
+  getSignalQBaseUrl,
+  getFractalQApiKey,
+  getSignalQApiUrl,
+  getApiKeyBySessionId,
+  getSignalQApiUrlBySessionId,
+} from './src/config/index.js';
+
+export { default as config } from './src/config/index.js';
+
+export default FractalQ;

package/package.json

@@ -0,0 +1,65 @@
+{
+  "name": "@fractalq/client",
+  "version": "2.1.1",
+  "description": "FractalQ JavaScript client — pass API keys from your app; this package never reads secret env vars (npm-safe).",
+  "type": "module",
+  "main": "./index.js",
+  "module": "./index.js",
+  "types": "./index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "import": "./index.js",
+      "default": "./index.js"
+    },
+    "./config": {
+      "types": "./index.d.ts",
+      "import": "./src/config/index.js",
+      "default": "./src/config/index.js"
+    },
+    "./useFractalQ": {
+      "types": "./useFractalQ.d.ts",
+      "import": "./useFractalQ.js",
+      "default": "./useFractalQ.js"
+    }
+  },
+  "peerDependencies": {
+    "react": ">=17.0.0"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    }
+  },
+  "files": [
+    "index.js",
+    "index.d.ts",
+    "useFractalQ.js",
+    "useFractalQ.d.ts",
+    "src/**/*.js",
+    "examples",
+    "LICENSE",
+    "README.md"
+  ],
+  "keywords": [
+    "fractalq",
+    "api-client",
+    "image-processing",
+    "typescript"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/fractalq/fractalq-client.git"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "test:smoke": "node examples/smoke-config.mjs"
+  }
+}