@fractalq/client 2.1.1

package/src/client/FractalQClient.js

@@ -0,0 +1,132 @@
+/**
+ * FractalQ API client — execute nodes via your backend proxy or direct SignalQ URL.
+ *
+ * Request tracking: the **canonical** job / request id is created by **FractalQ (SignalQ)** and
+ * returned on the execute response (`result.jobId`) and in async callbacks. Optional `jobId` in
+ * `execute()` is only for **client-side** correlation (e.g. temp file paths, local logs) until
+ * the server responds; prefer the server id for durable tracking and analytics.
+ */
+
+import { resolveExecuteBaseUrl } from './resolve-base-url.js';
+import { buildExecuteUrl } from './execute-url.js';
+import { resolveEffectiveJobId } from './effective-job-id.js';
+import { applyTempFileInputs } from './temp-inputs.js';
+import { buildProxyRequestBody } from './build-proxy-body.js';
+import { buildDirectRequestBody } from './build-direct-body.js';
+import { resolveAuthorizationHeader } from './authorization.js';
+import { readExecuteErrorMessage } from './http-error.js';
+import { shapeAsyncAcceptedResult, assertSyncSuccess } from './execute-response.js';
+
+export class FractalQClient {
+  constructor(options = {}) {
+    this.useBackendProxy = options.useBackendProxy !== false;
+    this.baseUrl = resolveExecuteBaseUrl(this.useBackendProxy, options.baseUrl);
+    this.apiKey = options.apiKey || options.nodeServiceApiKey || null;
+    this.sessionApiKey = options.sessionApiKey || this.apiKey || null;
+    this.timeout = options.timeout || 120000;
+    this.firebaseStorage = options.firebaseStorage || null;
+    this.firebaseConfig = options.firebaseConfig || null;
+    /** @type {(() => Promise<string|null|undefined>)|null} */
+    this.authTokenProvider = options.authTokenProvider || null;
+  }
+
+  async execute(nodeId, inputs = {}, options = {}) {
+    const url = buildExecuteUrl({
+      useBackendProxy: this.useBackendProxy,
+      baseUrl: this.baseUrl,
+      nodeId,
+      apiKey: this.apiKey,
+    });
+
+    const timeout = options.timeout || this.timeout;
+    const {
+      callbackUrl,
+      async: asyncMode = false,
+      jobId: passedJobId,
+      useTempFiles = false,
+      fractalqVersion,
+      sessionApiKey: optionsSessionApiKey,
+    } = options;
+
+    const effectiveJobId = resolveEffectiveJobId(passedJobId);
+    const sessionApiKey = optionsSessionApiKey || this.sessionApiKey;
+    if (!sessionApiKey) {
+      throw new Error(
+        'Session API key is required. Pass sessionApiKey in the constructor or in execute() options.'
+      );
+    }
+
+    let processedInputs = inputs;
+    if (useTempFiles && this.tempFiles && effectiveJobId) {
+      try {
+        processedInputs = await applyTempFileInputs(inputs, {
+          tempFiles: this.tempFiles,
+          effectiveJobId,
+          onProgress: options.onProgress,
+        });
+      } catch (tempError) {
+        console.warn('FractalQ: temp file upload failed, using original inputs:', tempError);
+      }
+    }
+
+    const requestBody = this.useBackendProxy
+      ? buildProxyRequestBody({
+          sessionApiKey,
+          processedInputs,
+          callbackUrl,
+          effectiveJobId,
+          asyncMode,
+          useTempFiles,
+          fractalqVersion,
+          options,
+        })
+      : buildDirectRequestBody({
+          processedInputs,
+          asyncMode,
+          callbackUrl,
+          fractalqVersion,
+        });
+
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), timeout);
+    const headers = { 'Content-Type': 'application/json' };
+
+    const authHeader = await resolveAuthorizationHeader(this.authTokenProvider);
+    if (authHeader) headers.Authorization = authHeader;
+
+    try {
+      const response = await fetch(url, {
+        method: 'POST',
+        headers,
+        body: JSON.stringify(requestBody),
+        signal: controller.signal,
+        credentials: 'include',
+      });
+      clearTimeout(timeoutId);
+
+      if (!response.ok) {
+        throw await readExecuteErrorMessage(response);
+      }
+
+      const result = await response.json();
+
+      if (asyncMode && callbackUrl && result.async) {
+        return shapeAsyncAcceptedResult(result, { effectiveJobId });
+      }
+
+      return assertSyncSuccess(result);
+    } catch (error) {
+      clearTimeout(timeoutId);
+      if (error.name === 'AbortError') {
+        throw new Error(`FractalQ API request timed out after ${timeout}ms`);
+      }
+      throw error;
+    }
+  }
+
+  async executeNode(nodeId, inputs = {}, options = {}) {
+    return this.execute(nodeId, inputs, options);
+  }
+}
+
+export default FractalQClient;

package/src/client/authorization.js

@@ -0,0 +1,11 @@
+/**
+ * Optional Bearer token from host-provided authTokenProvider.
+ */
+export async function resolveAuthorizationHeader(authTokenProvider) {
+  if (!authTokenProvider) return null;
+  try {
+    const t = await authTokenProvider();
+    if (t) return `Bearer ${t}`;
+  } catch (_) {}
+  return null;
+}

package/src/client/build-direct-body.js

@@ -0,0 +1,10 @@
+/**
+ * JSON body for direct SignalQ execute (no backend proxy).
+ */
+export function buildDirectRequestBody({ processedInputs, asyncMode, callbackUrl, fractalqVersion }) {
+  return {
+    ...processedInputs,
+    ...(asyncMode && callbackUrl ? { _callbackUrl: callbackUrl } : {}),
+    ...(fractalqVersion ? { _fractalqVersion: fractalqVersion } : {}),
+  };
+}

package/src/client/build-proxy-body.js

@@ -0,0 +1,26 @@
+/**
+ * JSON body for app proxy (e.g. POST /api/fractalq/execute).
+ */
+export function buildProxyRequestBody({
+  sessionApiKey,
+  processedInputs,
+  callbackUrl,
+  effectiveJobId,
+  asyncMode,
+  useTempFiles,
+  fractalqVersion,
+  options,
+}) {
+  return {
+    sessionApiKey,
+    inputs: { ...processedInputs },
+    options: {
+      callbackUrl,
+      jobId: effectiveJobId,
+      async: asyncMode,
+      useTempFiles,
+      fractalqVersion,
+      ...options,
+    },
+  };
+}

package/src/client/effective-job-id.js

@@ -0,0 +1,9 @@
+/**
+ * Client-side correlation id until FractalQ returns canonical jobId.
+ */
+export function resolveEffectiveJobId(passedJobId) {
+  if (typeof passedJobId === 'string' && passedJobId.trim()) {
+    return passedJobId.trim();
+  }
+  return `job-${Date.now()}-${Math.random().toString(36).slice(2, 10)}`;
+}

package/src/client/execute-response.js

@@ -0,0 +1,18 @@
+/**
+ * Normalize execute() JSON result (async vs sync).
+ */
+export function shapeAsyncAcceptedResult(result, { effectiveJobId }) {
+  return {
+    success: true,
+    async: true,
+    jobId: result.jobId || effectiveJobId,
+    message: result.message || 'Processing started. Results will be sent to callback URL.',
+  };
+}
+
+export function assertSyncSuccess(result) {
+  if (!result.success) {
+    throw new Error(result.error || 'FractalQ API execution failed');
+  }
+  return result;
+}

package/src/client/execute-url.js

@@ -0,0 +1,9 @@
+/**
+ * Full URL for POST execute.
+ */
+export function buildExecuteUrl({ useBackendProxy, baseUrl, nodeId, apiKey }) {
+  if (useBackendProxy) {
+    return `${baseUrl}/execute`;
+  }
+  return `${baseUrl}/${nodeId || apiKey}/execute`;
+}

package/src/client/http-error.js

@@ -0,0 +1,12 @@
+/**
+ * Parse error payload from non-OK execute response.
+ */
+export async function readExecuteErrorMessage(response) {
+  const errorText = await response.text();
+  let message = errorText;
+  try {
+    const errJson = JSON.parse(errorText);
+    if (errJson.error) message = errJson.error;
+  } catch (_) {}
+  return new Error(`FractalQ API error (${response.status}): ${message}`);
+}

package/src/client/resolve-base-url.js

@@ -0,0 +1,39 @@
+/**
+ * Resolve HTTP base for execute().
+ * - Proxy mode: relative path default `/api/fractalq`, or options.baseUrl from the host app.
+ * - Direct mode: no URL is hardcoded — pass options.baseUrl or set FRACTALQ_NODE_BASE_URL /
+ *   NEXT_PUBLIC_FRACTALQ_BASE_URL in the host environment (your app / .env.local), never inside this package.
+ */
+
+function trimBase(s) {
+  return String(s).trim().replace(/\/+$/, '');
+}
+
+export function resolveExecuteBaseUrl(useBackendProxy, explicitBaseUrl) {
+  const trimmed =
+    typeof explicitBaseUrl === 'string' && explicitBaseUrl.trim() ? trimBase(explicitBaseUrl) : null;
+
+  if (useBackendProxy) {
+    return trimmed || '/api/fractalq';
+  }
+
+  if (trimmed) {
+    return trimmed;
+  }
+
+  const fromEnv =
+    typeof process !== 'undefined'
+      ? (process.env.FRACTALQ_NODE_BASE_URL || process.env.NEXT_PUBLIC_FRACTALQ_BASE_URL || '')
+          .trim()
+      : '';
+  if (fromEnv) {
+    return trimBase(fromEnv);
+  }
+
+  throw new Error(
+    'FractalQClient: direct mode (useBackendProxy: false) needs a base URL. ' +
+      'Pass options.baseUrl (e.g. https://fractalq.com/api/node/api), or set FRACTALQ_NODE_BASE_URL ' +
+      'or NEXT_PUBLIC_FRACTALQ_BASE_URL in your application environment. ' +
+      'This package does not ship a default host (no embedded localhost or production URL).'
+  );
+}

package/src/client/temp-inputs.js

@@ -0,0 +1,20 @@
+/**
+ * Replace File/Blob/URL-ish strings with temp storage URLs when tempFiles is configured.
+ */
+export async function applyTempFileInputs(inputs, { tempFiles, effectiveJobId, onProgress }) {
+  if (!tempFiles || !effectiveJobId) {
+    return inputs;
+  }
+  const processedInputs = { ...inputs };
+  for (const [key, value] of Object.entries(inputs)) {
+    if (
+      value instanceof File ||
+      value instanceof Blob ||
+      (typeof value === 'string' && (value.startsWith('data:') || value.startsWith('http')))
+    ) {
+      const tempFile = await tempFiles.uploadTempFile(value, effectiveJobId, null, onProgress);
+      processedInputs[key] = tempFile.url;
+    }
+  }
+  return processedInputs;
+}

package/src/config/api-key.js

@@ -0,0 +1,13 @@
+/**
+ * Validate node / session API key passed by the host app.
+ */
+
+export function getFractalQApiKey(apiKey) {
+  if (!apiKey || typeof apiKey !== 'string' || !apiKey.trim()) {
+    throw new Error(
+      'FractalQ API key is required. Pass it from your application (host env, DB, or vault). ' +
+        '@fractalq/client does not load API keys from environment variables.'
+    );
+  }
+  return apiKey.trim();
+}

package/src/config/base-url.js

@@ -0,0 +1,17 @@
+/**
+ * Resolve SignalQ / FractalQ host base URL (npm-safe; no secret env reads).
+ */
+
+export function getSignalQBaseUrl(override) {
+  if (override && typeof override === 'string' && override.trim()) {
+    return override.replace(/\/+$/, '');
+  }
+  if (typeof process !== 'undefined' && process.env?.SIGNALQ_BASE_URL) {
+    const configured = String(process.env.SIGNALQ_BASE_URL).trim();
+    const looksLocal = /localhost|127\.0\.0\.1/i.test(configured);
+    if (!(process.env.NODE_ENV === 'production' && looksLocal)) {
+      return configured;
+    }
+  }
+  return 'https://fractalq.com';
+}

package/src/config/index.js

@@ -0,0 +1,21 @@
+/**
+ * FractalQ Client — configuration (npm-safe).
+ */
+
+export { getSignalQBaseUrl } from './base-url.js';
+export { getFractalQApiKey } from './api-key.js';
+export { getSignalQApiUrl } from './node-url.js';
+export { getApiKeyBySessionId, getSignalQApiUrlBySessionId } from './session-lookup.js';
+
+import { getSignalQBaseUrl } from './base-url.js';
+import { getFractalQApiKey } from './api-key.js';
+import { getSignalQApiUrl } from './node-url.js';
+import { getApiKeyBySessionId, getSignalQApiUrlBySessionId } from './session-lookup.js';
+
+export default {
+  getSignalQBaseUrl,
+  getFractalQApiKey,
+  getSignalQApiUrl,
+  getApiKeyBySessionId,
+  getSignalQApiUrlBySessionId,
+};

package/src/config/node-url.js

@@ -0,0 +1,8 @@
+import { getSignalQBaseUrl } from './base-url.js';
+import { getFractalQApiKey } from './api-key.js';
+
+export function getSignalQApiUrl(apiKey, baseUrl) {
+  const key = getFractalQApiKey(apiKey);
+  const base = getSignalQBaseUrl(baseUrl);
+  return `${base}/api/node/api/${key}/execute`;
+}

package/src/config/session-lookup.js

@@ -0,0 +1,26 @@
+import { getSignalQBaseUrl } from './base-url.js';
+import { getSignalQApiUrl } from './node-url.js';
+
+export async function getApiKeyBySessionId(sessionId, opts = {}) {
+  const base = getSignalQBaseUrl(opts.baseUrl);
+  const lookupUrl = `${base}/api/node/api?sessionId=${sessionId}`;
+  const headers = { 'Content-Type': 'application/json' };
+  if (opts.accountApiKey && String(opts.accountApiKey).trim()) {
+    headers.Authorization = `Bearer ${opts.accountApiKey.trim()}`;
+  }
+  const response = await fetch(lookupUrl, { method: 'GET', headers });
+  if (!response.ok) {
+    const err = await response.json().catch(() => ({ message: 'Failed to look up session' }));
+    throw new Error(err.message || `Session lookup failed: ${response.status}`);
+  }
+  const result = await response.json();
+  if (!result.success) {
+    throw new Error(result.message || 'Session lookup failed');
+  }
+  return result.data.apiKey;
+}
+
+export async function getSignalQApiUrlBySessionId(sessionId, opts = {}) {
+  const apiKey = await getApiKeyBySessionId(sessionId, opts);
+  return getSignalQApiUrl(apiKey, opts.baseUrl);
+}

package/src/image/ImageProcessor.js

@@ -0,0 +1,86 @@
+import { uploadToFirebase } from '../storage/firebase/index.js';
+import { prepareImageInputForExecute } from './prepare-image-input.js';
+import { resolveUpscaleCallbackUrl } from './resolve-callback-url.js';
+import { extractUpscaledImageData } from './extract-upscaled-output.js';
+
+export class ImageProcessor {
+  constructor(client) {
+    this.client = client;
+  }
+
+  async upscaleAndUpload(image, options = {}) {
+    const {
+      nodeId = null,
+      uploadPath = 'upscaled-images',
+      fileName = null,
+      onProgress = null,
+      inputs = {},
+      async: asyncMode = false,
+      callbackUrl = null,
+      jobId = null,
+      wokenmemeBaseUrl = null,
+    } = options;
+
+    try {
+      const imageInput = await prepareImageInputForExecute(image);
+      const finalCallbackUrl = resolveUpscaleCallbackUrl({
+        callbackUrl,
+        async: asyncMode,
+        wokenmemeBaseUrl,
+      });
+      const finalJobId = jobId || (asyncMode ? `job-${Date.now()}-${Math.random().toString(36).substr(2, 9)}` : null);
+
+      if (onProgress) onProgress({ step: 'upscaling', progress: 0.3 });
+
+      const nodeInputs = { input_0: imageInput, ...inputs };
+      const executeOptions = {
+        ...options,
+        async: asyncMode,
+        callbackUrl: finalCallbackUrl,
+        jobId: finalJobId,
+      };
+
+      const upscaleResult = await this.client.execute(nodeId, nodeInputs, executeOptions);
+
+      if (asyncMode && upscaleResult.async) {
+        if (onProgress) onProgress({ step: 'processing', progress: 0.5 });
+        return {
+          jobId: upscaleResult.jobId || finalJobId,
+          async: true,
+          message: upscaleResult.message || 'Processing started. Results will be sent to callback URL.',
+          callbackUrl: finalCallbackUrl,
+        };
+      }
+
+      if (onProgress) onProgress({ step: 'upscaling', progress: 0.6 });
+
+      const upscaledImageData = extractUpscaledImageData(upscaleResult);
+      if (!upscaledImageData) {
+        throw new Error('No upscaled image data returned from API');
+      }
+
+      if (onProgress) onProgress({ step: 'uploading', progress: 0.7 });
+
+      const uploadedUrl = await uploadToFirebase({
+        imageData: upscaledImageData,
+        path: uploadPath,
+        fileName: fileName || `upscaled-${Date.now()}.png`,
+        onProgress: (progress) => {
+          if (onProgress) {
+            onProgress({ step: 'uploading', progress: 0.7 + progress * 0.3 });
+          }
+        },
+        firebaseStorage: this.client.firebaseStorage,
+        firebaseConfig: this.client.firebaseConfig,
+      });
+
+      if (onProgress) onProgress({ step: 'complete', progress: 1.0 });
+      return uploadedUrl;
+    } catch (error) {
+      console.error('FractalQ upscale and upload error:', error);
+      throw error;
+    }
+  }
+}
+
+export default ImageProcessor;

package/src/image/extract-upscaled-output.js

@@ -0,0 +1,5 @@
+export function extractUpscaledImageData(upscaleResult) {
+  return (
+    upscaleResult.data?.output_0 || upscaleResult.data?.image || upscaleResult.data || null
+  );
+}

package/src/image/file-to-base64.js

@@ -0,0 +1,15 @@
+/**
+ * Read File/Blob as raw base64 payload (no data: prefix).
+ */
+export function fileToBase64Data(file) {
+  return new Promise((resolve, reject) => {
+    const reader = new FileReader();
+    reader.onload = () => {
+      const base64 = reader.result;
+      const base64Data = base64.includes(',') ? base64.split(',')[1] : base64;
+      resolve(base64Data);
+    };
+    reader.onerror = reject;
+    reader.readAsDataURL(file);
+  });
+}

package/src/image/index.js

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

package/src/image/prepare-image-input.js

@@ -0,0 +1,11 @@
+import { fileToBase64Data } from './file-to-base64.js';
+
+export async function prepareImageInputForExecute(image) {
+  if (typeof image === 'string') {
+    return image;
+  }
+  if (image instanceof File || image instanceof Blob) {
+    return fileToBase64Data(image);
+  }
+  throw new Error('Invalid image input. Must be File, Blob, or URL string.');
+}

package/src/image/resolve-callback-url.js

@@ -0,0 +1,10 @@
+/**
+ * Default async callback URL in the browser when host does not pass one.
+ */
+export function resolveUpscaleCallbackUrl({ callbackUrl, async: asyncMode, wokenmemeBaseUrl }) {
+  if (!asyncMode) return callbackUrl;
+  if (callbackUrl) return callbackUrl;
+  if (typeof window === 'undefined') return null;
+  const baseUrl = wokenmemeBaseUrl || window.location.origin;
+  return `${baseUrl}/api/fractalq/callback`;
+}

package/src/pipeline/PipelineProcessor.js

@@ -0,0 +1,32 @@
+import { mergeNodeInputs } from './merge-node-inputs.js';
+import { nextStageData } from './apply-stage-result.js';
+
+export class PipelineProcessor {
+  constructor(client) {
+    this.client = client;
+  }
+
+  async execute(nodePipeline, options = {}) {
+    let currentData = options.initialData || {};
+
+    for (let i = 0; i < nodePipeline.length; i++) {
+      const { nodeId, inputs = {}, transform } = nodePipeline[i];
+      const nodeInputs = mergeNodeInputs(currentData, inputs);
+
+      if (options.onProgress) {
+        options.onProgress({
+          step: `node-${i + 1}`,
+          progress: (i + 1) / nodePipeline.length,
+          nodeId,
+        });
+      }
+
+      const result = await this.client.execute(nodeId, nodeInputs, options);
+      currentData = nextStageData(result, transform);
+    }
+
+    return { success: true, data: currentData };
+  }
+}
+
+export default PipelineProcessor;

package/src/pipeline/apply-stage-result.js

@@ -0,0 +1,9 @@
+/**
+ * Apply optional transform to execute() result data for the next stage.
+ */
+export function nextStageData(result, transform) {
+  if (transform && typeof transform === 'function') {
+    return transform(result.data);
+  }
+  return result.data;
+}

package/src/pipeline/index.js

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

package/src/pipeline/merge-node-inputs.js

@@ -0,0 +1,9 @@
+/**
+ * Merge accumulated pipeline data with the next node's explicit inputs.
+ */
+export function mergeNodeInputs(currentData, inputs) {
+  return {
+    ...currentData,
+    ...inputs,
+  };
+}

package/src/storage/firebase/image-to-blob.js

@@ -0,0 +1,21 @@
+import { base64DataUrlToBlob } from '../shared/base64-data-url-to-blob.js';
+
+/**
+ * Normalize imageData (blob, file, URL string, base64) to Blob for upload.
+ */
+export async function imageDataToBlob(imageData) {
+  if (imageData instanceof Blob || imageData instanceof File) {
+    return imageData;
+  }
+  if (typeof imageData === 'string') {
+    if (imageData.startsWith('data:')) {
+      return base64DataUrlToBlob(imageData);
+    }
+    if (imageData.startsWith('http://') || imageData.startsWith('https://')) {
+      const response = await fetch(imageData);
+      return response.blob();
+    }
+    return base64DataUrlToBlob(`data:image/png;base64,${imageData}`);
+  }
+  throw new Error('Invalid image data format');
+}

package/src/storage/firebase/index.js

@@ -0,0 +1,2 @@
+export { getStorageInstance } from './instance.js';
+export { uploadToFirebase, uploadFileToFirebase } from './upload-to-firebase.js';

package/src/storage/firebase/instance.js

@@ -0,0 +1,52 @@
+/**
+ * Resolve Firebase Storage instance from explicit options or env (browser).
+ */
+
+let storage = null;
+
+export const getStorageInstance = (options = {}) => {
+  if (options.firebaseStorage) {
+    return options.firebaseStorage;
+  }
+  if (storage) return storage;
+
+  if (typeof window === 'undefined') {
+    return null;
+  }
+
+  if (options.firebaseConfig) {
+    try {
+      const { initializeApp } = require('firebase/app');
+      const { getStorage } = require('firebase/storage');
+      const app = initializeApp(options.firebaseConfig);
+      storage = getStorage(app);
+      return storage;
+    } catch (error) {
+      console.warn('Failed to initialize Firebase from provided config:', error);
+    }
+  }
+
+  try {
+    const { initializeApp, getApps } = require('firebase/app');
+    const { getStorage } = require('firebase/storage');
+    const apps = getApps();
+    if (apps.length === 0) {
+      const firebaseConfig = {
+        apiKey: process.env.NEXT_PUBLIC_FIREBASE_API_KEY,
+        authDomain: process.env.NEXT_PUBLIC_FIREBASE_AUTH_DOMAIN,
+        projectId: process.env.NEXT_PUBLIC_FIREBASE_PROJECT_ID,
+        storageBucket: process.env.NEXT_PUBLIC_FIREBASE_STORAGE_BUCKET,
+        messagingSenderId: process.env.NEXT_PUBLIC_FIREBASE_MESSAGING_SENDER_ID,
+        appId: process.env.NEXT_PUBLIC_FIREBASE_APP_ID,
+      };
+      const app = initializeApp(firebaseConfig);
+      storage = getStorage(app);
+    } else {
+      storage = getStorage(apps[0]);
+    }
+  } catch (fallbackError) {
+    console.warn('Firebase Storage not available:', fallbackError);
+  }
+
+  return storage;
+};