@call-me-sensei/toonlab 0.4.19 → 0.4.21

package/database/providers.mjs

@@ -1,3 +1,9 @@
+import {
+  createPatinaInput,
+  normalizePatinaResult,
+  PATINA_MATERIAL_MODEL,
+} from './fal-patina.mjs';
+
 const IMAGE_KINDS = new Set(['image', 'texture_image', 'concept_image']);
 const TRIPO_API_BASE = 'https://api.tripo3d.ai/v2/openapi';
 const TRIPO_MODEL_VERSION = 'v2.5-20250123';
@@ -52,6 +58,7 @@ const ARK_IMAGE_SIZES = {
 function providerKey(provider) {
   const names = {
     ark: ['ARK_API_KEY', 'ARK_API_KEYS'],
+    fal: ['FAL_KEY', 'FAL_KEYS'],
     gemini: ['GEMINI_API_KEY', 'GEMINI_API_KEYS'],
     openai: ['OPENAI_API_KEY', 'OPENAI_API_KEYS'],
     tripo: ['TRIPO_API_KEY', 'TRIPO_API_KEYS'],
@@ -64,12 +71,63 @@ function providerKey(provider) {
   throw new Error(`${provider} is not configured in the server environment`);
 }
 
-async function checkedJson(response, provider) {
+async function runFalPatina(request, key) {
+  if (request.kind !== 'material') throw new Error(`Fal cannot serve generation kind ${request.kind}.`);
+  const input = createPatinaInput(request);
+  const response = await fetch(`https://fal.run/${PATINA_MATERIAL_MODEL}`, {
+    body: JSON.stringify(input),
+    headers: {
+      authorization: `Key ${key}`,
+      'content-type': 'application/json',
+    },
+    method: 'POST',
+    signal: AbortSignal.timeout(15 * 60_000),
+  });
+  const data = await checkedJson(response, 'Fal Patina');
+  return {
+    material: normalizePatinaResult(data, input),
+    provider: 'fal',
+  };
+}
+
+function boundedProviderText(value, maximumLength = 500) {
+  if (value === undefined || value === null) return null;
+  return String(value).replace(/[\u0000-\u001f\u007f]/g, ' ').trim().slice(0, maximumLength) || null;
+}
+
+function sanitizedTraceId(value) {
+  const traceId = boundedProviderText(value, 160);
+  if (!traceId) return null;
+  return /^[A-Za-z0-9._:/-]+$/.test(traceId) ? traceId : '[redacted-invalid-trace-id]';
+}
+
+function providerErrorMetadata(response, body, context = {}) {
+  const providerCode = body?.error?.code ?? body?.code ?? null;
+  return {
+    providerCode: typeof providerCode === 'number' || typeof providerCode === 'string'
+      ? providerCode
+      : null,
+    providerMessage: boundedProviderText(body?.error?.message ?? body?.message),
+    providerRequestPhase: boundedProviderText(context.requestPhase, 64),
+    providerResponseReceived: true,
+    providerStatus: response.status,
+    providerSuggestion: boundedProviderText(body?.error?.suggestion ?? body?.suggestion),
+    retryAfter: boundedProviderText(response.headers.get('retry-after'), 160),
+    traceId: sanitizedTraceId(response.headers.get('x-tripo-trace-id')),
+  };
+}
+
+function createProviderResponseError(provider, response, body, context = {}) {
+  const metadata = providerErrorMetadata(response, body, context);
+  return Object.assign(new Error(`${provider} request failed (${response.status}): ${
+    metadata.providerMessage ?? 'unknown provider error'
+  }`), metadata);
+}
+
+export async function checkedJson(response, provider, context = {}) {
   const body = await response.json().catch(() => null);
   if (!response.ok) {
-    throw Object.assign(new Error(`${provider} request failed (${response.status}): ${
-      body?.error?.message ?? body?.message ?? 'unknown provider error'
-    }`), { providerStatus: response.status });
+    throw createProviderResponseError(provider, response, body, context);
   }
   return body;
 }
@@ -258,9 +316,16 @@ async function tripoJson(path, key, init = {}) {
     },
     signal: init.signal ?? AbortSignal.timeout(2 * 60_000),
   });
-  const envelope = await checkedJson(response, 'Tripo');
+  const requestPhase = path === '/task' && init.method === 'POST'
+    ? 'task-create'
+    : path === '/upload' && init.method === 'POST'
+      ? 'image-upload'
+      : path.startsWith('/task/') && init.method === 'GET'
+        ? 'task-poll'
+        : 'tripo-request';
+  const envelope = await checkedJson(response, 'Tripo', { requestPhase });
   if (envelope?.code !== 0 || !envelope?.data) {
-    throw new Error(`Tripo request failed: ${envelope?.message ?? 'missing response data'}`);
+    throw createProviderResponseError('Tripo', response, envelope, { requestPhase });
   }
   return envelope.data;
 }
@@ -280,15 +345,88 @@ async function uploadTripoImage(reference, key) {
   };
 }
 
+function tripoModelVersion(request) {
+  const modelVersion = request.modelVersion ?? TRIPO_MODEL_VERSION;
+  if (!/^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/.test(modelVersion)) {
+    throw new RangeError('Tripo modelVersion must be a provider snapshot identifier.');
+  }
+  return modelVersion;
+}
+
+function tripoGenerationOptions(request, modelVersion) {
+  const options = {};
+  if (request.faceLimit !== undefined) {
+    const geometryQuality = request.geometryQuality ?? 'standard';
+    const maximumByModel = {
+      'P1-20260311': 20_000,
+      'v2.5-20250123': 500_000,
+      'v3.0-20250812': geometryQuality === 'detailed' ? 2_000_000 : 1_500_000,
+      'v3.1-20260211': geometryQuality === 'detailed' ? 2_000_000 : 1_500_000,
+    };
+    const maximum = maximumByModel[modelVersion];
+    if (maximum === undefined) {
+      throw new RangeError(`Explicit Tripo faceLimit is not verified for model ${modelVersion}.`);
+    }
+    if (!Number.isInteger(request.faceLimit) || request.faceLimit < 48 || request.faceLimit > maximum) {
+      throw new RangeError(`Tripo ${modelVersion} faceLimit must be an integer from 48 through ${maximum}.`);
+    }
+    options.face_limit = request.faceLimit;
+  }
+  if (request.modelSeed !== undefined) {
+    if (!Number.isSafeInteger(request.modelSeed)) throw new RangeError('Tripo modelSeed must be a safe integer.');
+    options.model_seed = request.modelSeed;
+  }
+  if (request.textureSeed !== undefined) {
+    if (!Number.isSafeInteger(request.textureSeed)) throw new RangeError('Tripo textureSeed must be a safe integer.');
+    options.texture_seed = request.textureSeed;
+  }
+  for (const [requestKey, payloadKey] of [
+    ['texture', 'texture'],
+    ['pbr', 'pbr'],
+    ['exportUv', 'export_uv'],
+  ]) {
+    if (request[requestKey] !== undefined) {
+      if (typeof request[requestKey] !== 'boolean') {
+        throw new TypeError(`Tripo ${requestKey} must be boolean.`);
+      }
+      options[payloadKey] = request[requestKey];
+    }
+  }
+  if (request.textureQuality !== undefined) {
+    if (!['standard', 'detailed', 'extreme'].includes(request.textureQuality)) {
+      throw new RangeError('Tripo textureQuality must be standard, detailed, or extreme.');
+    }
+    options.texture_quality = request.textureQuality;
+  }
+  if (request.textureAlignment !== undefined) {
+    if (!['original_image', 'geometry'].includes(request.textureAlignment)) {
+      throw new RangeError('Tripo textureAlignment must be original_image or geometry.');
+    }
+    options.texture_alignment = request.textureAlignment;
+  }
+  if (request.geometryQuality !== undefined) {
+    if (!['standard', 'detailed'].includes(request.geometryQuality)) {
+      throw new RangeError('Tripo geometryQuality must be standard or detailed.');
+    }
+    if (!['v3.0-20250812', 'v3.1-20260211'].includes(modelVersion)) {
+      throw new RangeError('Tripo geometryQuality is supported only for v3.0-20250812 and v3.1-20260211.');
+    }
+    options.geometry_quality = request.geometryQuality;
+  }
+  return options;
+}
+
 async function runTripo(request, key) {
   let payload;
+  const modelVersion = tripoModelVersion(request);
   if (request.kind === 'image_to_model') {
     const reference = request.referenceImages?.[0];
     if (!reference) throw new Error('Image-to-3D requires one reference image');
     payload = {
       type: 'image_to_model',
-      model_version: TRIPO_MODEL_VERSION,
+      model_version: modelVersion,
       file: await uploadTripoImage(reference, key),
+      ...tripoGenerationOptions(request, modelVersion),
     };
   } else if (request.kind === 'multiview_to_model') {
     const views = request.viewImages ?? [];
@@ -297,10 +435,11 @@ async function runTripo(request, key) {
     }
     payload = {
       type: 'multiview_to_model',
-      model_version: TRIPO_MODEL_VERSION,
+      model_version: modelVersion,
       files: await Promise.all(
         views.slice(0, 4).map((view) => view ? uploadTripoImage(view, key) : {}),
       ),
+      ...tripoGenerationOptions(request, modelVersion),
     };
   } else if (request.kind === 'model_segment') {
     if (!request.originalTaskId) throw new Error('Model segmentation requires the original Tripo task id');
@@ -312,8 +451,9 @@ async function runTripo(request, key) {
     const styleSuffix = TRIPO_STYLES[request.style] ?? TRIPO_STYLES.stylized;
     payload = {
       type: 'text_to_model',
-      model_version: TRIPO_MODEL_VERSION,
+      model_version: modelVersion,
       prompt: `${request.prompt ?? request.user ?? ''}${styleSuffix}`,
+      ...tripoGenerationOptions(request, modelVersion),
     };
   }
   const data = await tripoJson('/task', key, {
@@ -322,7 +462,12 @@ async function runTripo(request, key) {
     method: 'POST',
   });
   if (!data.task_id) throw new Error('Tripo task creation returned no task id');
-  return { pending: true, provider: 'tripo', taskId: data.task_id };
+  return {
+    modelVersion: request.kind === 'model_segment' ? null : modelVersion,
+    pending: true,
+    provider: 'tripo',
+    taskId: data.task_id,
+  };
 }
 
 function meshyImageDataUri(reference) {
@@ -345,17 +490,49 @@ async function meshyJson(path, key, init = {}) {
   return checkedJson(response, 'Meshy');
 }
 
+function meshyGenerationOptions(request) {
+  const textureResolution = request.textureResolution ?? '2k';
+  if (!['2k', '4k', '8k'].includes(textureResolution)) {
+    throw new RangeError('Meshy textureResolution must be 2k, 4k, or 8k.');
+  }
+  const options = {
+    alpha_thumbnail: request.alphaThumbnail ?? true,
+    enable_pbr: request.pbr ?? true,
+    image_enhancement: request.imageEnhancement ?? true,
+    remove_lighting: request.removeLighting ?? true,
+    should_remesh: request.shouldRemesh ?? false,
+    should_texture: request.texture ?? true,
+    target_formats: ['glb'],
+    texture_resolution: textureResolution,
+  };
+  for (const [requestKey, payloadKey] of [
+    ['alphaThumbnail', 'alpha_thumbnail'],
+    ['imageEnhancement', 'image_enhancement'],
+    ['pbr', 'enable_pbr'],
+    ['removeLighting', 'remove_lighting'],
+    ['shouldRemesh', 'should_remesh'],
+    ['texture', 'should_texture'],
+  ]) {
+    if (request[requestKey] !== undefined && typeof request[requestKey] !== 'boolean') {
+      throw new TypeError(`Meshy ${requestKey} must be boolean.`);
+    }
+    if (request[requestKey] !== undefined) options[payloadKey] = request[requestKey];
+  }
+  if (request.texturePrompt !== undefined) {
+    if (typeof request.texturePrompt !== 'string' || request.texturePrompt.length > 600) {
+      throw new RangeError('Meshy texturePrompt must be a string of at most 600 characters.');
+    }
+    if (request.texturePrompt.trim()) options.texture_prompt = request.texturePrompt.trim();
+  }
+  return options;
+}
+
 async function runMeshy(request, key) {
   let path;
   let payload;
   const shared = {
     ai_model: MESHY_MODEL_VERSION,
-    alpha_thumbnail: true,
-    enable_pbr: true,
-    should_remesh: false,
-    should_texture: true,
-    target_formats: ['glb'],
-    texture_resolution: '2k',
+    ...meshyGenerationOptions(request),
   };
   if (request.kind === 'image_to_model') {
     path = '/v1/image-to-3d';
@@ -382,6 +559,7 @@ async function runMeshy(request, key) {
   });
   if (!data?.result) throw new Error('Meshy task creation returned no task id');
   return {
+    modelVersion: MESHY_MODEL_VERSION,
     pending: true,
     provider: 'meshy',
     taskId: data.result,
@@ -390,6 +568,7 @@ async function runMeshy(request, key) {
 
 export async function runProvider(provider, request) {
   const key = providerKey(provider);
+  if (provider === 'fal') return runFalPatina(request, key);
   if (provider === 'gemini') return runGemini(request, key);
   if (provider === 'openai' || provider === 'ark') {
     return runOpenAiOrArk(provider, request, key);