@forgeax-extension/character-3d 0.1.2

package/server/providers/meshy-direct-client.ts

@@ -0,0 +1,223 @@
+// Local Meshy OpenAPI transport. Production Meshy stays on LiteLLM
+// (`GatewayClient` + `/v1/3d/generations`). This client is only constructed
+// when GEN3D_MESHY_DIRECT=1 and MESHY_API_KEY are set — a recording-machine
+// override that talks to api.meshy.ai with the operator's own credits.
+//
+// It presents the same post/get/pollTask/download surface as GatewayClient
+// so MeshyProvider does not grow a second generate/rig/animate implementation.
+// Submit/poll go to `/openapi/v1/...`; responses are reshaped to the gateway
+// `data[]` envelope that extractGatewayUrls / extractRigUrls already understand.
+
+import { GatewayClient, httpError, type FetchLike } from './gateway-client';
+import { MESHY_GATEWAY_MODELS } from './gateway-models';
+import type { LitellmEnv } from '../env';
+
+export interface DirectMeshyClientDeps {
+  env: LitellmEnv;
+  fetchImpl?: FetchLike;
+  sleep?: (ms: number) => Promise<void>;
+}
+
+const DIRECT_FAILURE = new Set(['failed', 'error', 'fail', 'canceled', 'cancelled']);
+
+// Survives a new DirectMeshyClient between submit and poll. MeshyProvider
+// used to construct a fresh client for every gateway() call.
+const pollPathByTaskId = new Map<string, string>();
+
+export function meshyDirectRoute(model: unknown): { submit: string; pollPrefix: string } | null {
+  switch (model) {
+    case MESHY_GATEWAY_MODELS.text:
+    case MESHY_GATEWAY_MODELS.refine:
+      // Meshy retired /openapi/v1/text-to-3d (404 NoMatchingRoute as of 2026-08).
+      return { submit: '/openapi/v2/text-to-3d', pollPrefix: '/openapi/v2/text-to-3d' };
+    case MESHY_GATEWAY_MODELS.image:
+      return { submit: '/openapi/v1/image-to-3d', pollPrefix: '/openapi/v1/image-to-3d' };
+    case MESHY_GATEWAY_MODELS.views:
+      return { submit: '/openapi/v1/multi-image-to-3d', pollPrefix: '/openapi/v1/multi-image-to-3d' };
+    case MESHY_GATEWAY_MODELS.autoRig:
+      return { submit: '/openapi/v1/rigging', pollPrefix: '/openapi/v1/rigging' };
+    case MESHY_GATEWAY_MODELS.animation:
+      return { submit: '/openapi/v1/animations', pollPrefix: '/openapi/v1/animations' };
+    default:
+      return null;
+  }
+}
+
+export function toGatewayMeshyTask(direct: Record<string, unknown>): Record<string, unknown> {
+  const status = normalizeDirectStatus(direct.status);
+  const data = collectDirectData(direct);
+  const id = firstString(direct.id, direct.result);
+  return {
+    ...direct,
+    ...(id ? { id } : {}),
+    status,
+    data,
+  };
+}
+
+export class DirectMeshyClient extends GatewayClient {
+  private readonly pollPathById = new Map<string, string>();
+  private readonly fetchDirect: FetchLike;
+  private readonly key: string;
+  private readonly host: string;
+
+  constructor(deps: DirectMeshyClientDeps) {
+    super(deps);
+    this.fetchDirect = deps.fetchImpl ?? ((url, init) => fetch(url, init));
+    this.key = deps.env.apiKey;
+    this.host = deps.env.baseUrl.replace(/\/+$/, '');
+  }
+
+  override async post(path: string, body: unknown): Promise<Record<string, unknown>> {
+    if (path !== '/v1/3d/generations') {
+      throw Object.assign(new Error(`meshy direct client does not post ${path}`), {
+        code: 'provider_bad_request',
+      });
+    }
+    const payload = asRecord(body);
+    if (!payload) {
+      throw Object.assign(new Error('meshy direct submit needs a JSON object'), {
+        code: 'provider_bad_request',
+      });
+    }
+    const route = meshyDirectRoute(payload.model);
+    if (!route) {
+      throw Object.assign(new Error(`meshy direct: unsupported model ${String(payload.model)}`), {
+        code: 'provider_bad_request',
+      });
+    }
+    const { model: _model, ...rest } = payload;
+    const resp = await this.fetchDirect(`${this.host}${route.submit}`, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        Authorization: `Bearer ${this.key}`,
+      },
+      body: JSON.stringify(rest),
+    });
+    const json = await readJson(resp);
+    const id = firstString(json.result, json.id);
+    if (!id) {
+      throw Object.assign(new Error('meshy direct submit returned no task id'), {
+        code: 'provider_no_task',
+      });
+    }
+    const pollPath = `${route.pollPrefix}/${id}`;
+    this.pollPathById.set(id, pollPath);
+    pollPathByTaskId.set(id, pollPath);
+    return { id, status: 'processing' };
+  }
+
+  override async get(path: string): Promise<Record<string, unknown>> {
+    const id = path.split('/').filter(Boolean).pop() ?? '';
+    const pollPath =
+      this.pollPathById.get(id) ?? pollPathByTaskId.get(id) ?? guessPollPath(path, id);
+    const resp = await this.fetchDirect(`${this.host}${pollPath}`, {
+      method: 'GET',
+      headers: { Authorization: `Bearer ${this.key}` },
+    });
+    return toGatewayMeshyTask(await readJson(resp));
+  }
+}
+
+function guessPollPath(gatewayPath: string, id: string): string {
+  if (gatewayPath.startsWith('/openapi/')) return gatewayPath;
+  return `/openapi/v1/image-to-3d/${id}`;
+}
+
+function normalizeDirectStatus(status: unknown): string {
+  const value = String(status ?? '').toLowerCase();
+  if (value === 'succeeded') return 'succeeded';
+  if (DIRECT_FAILURE.has(value)) return 'failed';
+  return value || 'pending';
+}
+
+function collectDirectData(direct: Record<string, unknown>): Array<Record<string, unknown>> {
+  const data: Array<Record<string, unknown>> = [];
+  const seen = new Set<string>();
+  const push = (url: unknown, format: string, name: string, type = 'mesh') => {
+    if (typeof url !== 'string' || !url || seen.has(`${name}:${format}`)) return;
+    seen.add(`${name}:${format}`);
+    data.push({ url, type, format, name: `${name}.${format}` });
+  };
+
+  const modelUrls = asRecord(direct.model_urls);
+  if (modelUrls) {
+    for (const [fmt, url] of Object.entries(modelUrls)) {
+      if (typeof url === 'string' && url) push(url, fmt, 'model');
+    }
+  }
+
+  // Official poll `result` is an object. Submit/pending may put the task id
+  // string in `result`, so fall back to the top-level payload for those fields.
+  const result = asRecord(direct.result) ?? {};
+  const character = asRecord(result.rigged_character) ?? asRecord(direct.rigged_character) ?? {};
+  // Official 2026 rig envelope is flat on `result`:
+  //   rigged_character_glb_url / rigged_character_fbx_url
+  // Older fixtures nest `{ glb_url, fbx_url }` under `rigged_character`.
+  push(
+    firstString(result.rigged_character_glb_url, character.glb_url, direct.rigged_character_glb_url),
+    'glb',
+    'Character_output',
+  );
+  push(
+    firstString(result.rigged_character_fbx_url, character.fbx_url, direct.rigged_character_fbx_url),
+    'fbx',
+    'Character_output',
+  );
+
+  const animations = asRecord(result.basic_animations) ?? asRecord(direct.basic_animations);
+  if (animations) {
+    const walking = asRecord(animations.walking) ?? {};
+    const running = asRecord(animations.running) ?? {};
+    push(
+      firstString(animations.walking_glb_url, walking.glb_url),
+      'glb',
+      'Animation_Walking_withSkin',
+    );
+    push(
+      firstString(animations.walking_fbx_url, walking.fbx_url),
+      'fbx',
+      'Animation_Walking_withSkin',
+    );
+    push(
+      firstString(animations.running_glb_url, running.glb_url),
+      'glb',
+      'Animation_Running_withSkin',
+    );
+    push(
+      firstString(animations.running_fbx_url, running.fbx_url),
+      'fbx',
+      'Animation_Running_withSkin',
+    );
+  }
+
+  // Official animate result (PLAN 2.3). Same last-wins format key as generate.
+  push(firstString(result.animation_glb_url, direct.animation_glb_url), 'glb', 'animation');
+  push(firstString(result.animation_fbx_url, direct.animation_fbx_url), 'fbx', 'animation');
+
+  const thumb = firstString(direct.thumbnail_url, result.thumbnail_url);
+  if (thumb) data.push({ url: thumb, type: 'preview', format: 'png', name: 'preview.png' });
+  return data;
+}
+
+function asRecord(value: unknown): Record<string, unknown> | null {
+  return typeof value === 'object' && value !== null && !Array.isArray(value)
+    ? (value as Record<string, unknown>)
+    : null;
+}
+
+function firstString(...values: unknown[]): string | null {
+  for (const value of values) {
+    if (typeof value === 'string' && value.trim()) return value.trim();
+  }
+  return null;
+}
+
+async function readJson(resp: Response): Promise<Record<string, unknown>> {
+  if (!resp.ok) {
+    const body = await resp.text().catch(() => '');
+    throw httpError(resp.status, body);
+  }
+  return (await resp.json()) as Record<string, unknown>;
+}