@forgeax-extension/character-3d 0.1.2

package/server/providers/hunyuan-rest.ts

@@ -0,0 +1,317 @@
+// HunyuanRestProvider — real client for Hunyuan sub-capabilities via LiteLLM gateway.
+//
+// Unlike the workflow provider (async submit/poll), most REST sub-capabilities are
+// SYNCHRONOUS on the gateway: a single POST /v1/3d/generations with the appropriate
+// `model` returns immediately with `status=succeeded` and `data[]` filled.
+// low_poly remains async (submit then poll). Auth uses a standard bearer header.
+//
+// Decoupling (ADR-0001): talks to the remote gateway and returns pure results with
+// downloaded bytes. `fetchImpl`/`downloadImpl` are injectable for smokes.
+
+import type { HunyuanEnv } from '../env';
+import { audit } from '../audit';
+import { RateGuard } from '../rate-guard';
+import { extractGatewayUrls } from './gateway-data';
+import {
+  GatewayClient,
+  gatewayErrorMessage,
+  normalizeGatewayStatus,
+  type FetchLike,
+} from './gateway-client';
+import { HUNYUAN_GATEWAY_MODELS } from './gateway-models';
+
+const GATEWAY_SUBMIT = '/v1/3d/generations';
+const GATEWAY_POLL = '/v1/3d/tasks';
+
+export type DownloadLike = (url: string) => Promise<Uint8Array>;
+
+export interface HunyuanRestDeps {
+  env: HunyuanEnv;
+  slug: string;
+  fetchImpl?: FetchLike;
+  downloadImpl?: DownloadLike;
+  rateGuard?: RateGuard;
+  sleep?: (ms: number) => Promise<void>;
+}
+
+export interface PoseStandardizationInput {
+  imageUrl: string;
+  footnote?: string;
+}
+
+// One downloaded model file from a rig/motion/low_poly response.
+export interface ModelFileOut {
+  format: 'glb' | 'fbx';
+  data: Uint8Array;
+}
+
+export interface AutoRigInput {
+  glbUrl: string;
+  footnote?: string;
+}
+
+export interface ApplyMotionInput {
+  fbxUrl: string;
+  motionType: number;
+}
+
+export interface LowPolyInput {
+  glbUrl: string;
+  polygonType?: 'triangle' | 'quadrilateral';
+  detailLevel?: 'high' | 'medium' | 'low';
+  footnote?: string;
+}
+
+export interface RigMotionResult {
+  sourceJobId: string | null;
+  files: ModelFileOut[];
+}
+
+export interface LowPolyResult {
+  sourceJobId: string | null;
+  glb: Uint8Array;
+  previewImage: Uint8Array | null;
+}
+
+export interface PoseStandardizationResult {
+  sourceJobId: string | null;
+  imageData: Uint8Array;
+  sourceUrl: string;
+}
+
+export class HunyuanRestProvider {
+  private readonly env: HunyuanEnv;
+  private readonly slug: string;
+  private readonly fetchImpl: FetchLike;
+  private readonly downloadImpl: DownloadLike;
+  private readonly rateGuard: RateGuard;
+  private readonly sleep: (ms: number) => Promise<void>;
+
+  constructor(deps: HunyuanRestDeps) {
+    this.env = deps.env;
+    this.slug = deps.slug;
+    this.fetchImpl = deps.fetchImpl ?? ((url, init) => fetch(url, init));
+    this.downloadImpl =
+      deps.downloadImpl ??
+      (async (url) => this.gateway().download(url, { format: urlFormat(url), image: isImageUrl(url) }));
+    this.rateGuard = deps.rateGuard ?? new RateGuard(this.env.rateLimitPerMin);
+    this.sleep = deps.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
+  }
+
+  // pose_standardization: gateway may return sync data[] or an async task.
+  async poseStandardization(input: PoseStandardizationInput): Promise<PoseStandardizationResult> {
+    const payload: Record<string, unknown> = {
+      model: HUNYUAN_GATEWAY_MODELS.pose,
+      image_url: input.imageUrl,
+    };
+    if (input.footnote) payload.footnote = input.footnote;
+
+    this.rateGuard.check();
+    const submitted = await this.post(payload);
+    const resp = await this.resolveSyncOrPoll(submitted, 'pose_standardization');
+    const sourceJobId = (resp.id as string) ?? (submitted.id as string) ?? null;
+
+    if (isGatewayFailed(resp)) {
+      const msg = gatewayErrorMessage(resp) ?? 'unknown';
+      await audit(this.slug, { ts: new Date().toISOString(), provider: 'hunyuan_rest', mode: 'image', event: 'rest_failed', sourceJobId, detail: msg });
+      throw Object.assign(new Error(`hunyuan pose_standardization failed: ${msg}`), { code: 'provider_failed' });
+    }
+
+    const url = extractSingleImageUrl(resp);
+    if (!url) {
+      await audit(this.slug, { ts: new Date().toISOString(), provider: 'hunyuan_rest', mode: 'image', event: 'rest_no_output', sourceJobId });
+      throw Object.assign(new Error('hunyuan pose_standardization returned no image url'), { code: 'provider_no_output' });
+    }
+
+    const imageData = await this.downloadImpl(url);
+    await audit(this.slug, { ts: new Date().toISOString(), provider: 'hunyuan_rest', mode: 'image', event: 'rest_succeeded', sourceJobId });
+    return { sourceJobId, imageData, sourceUrl: url };
+  }
+
+  // auto_rigging: textured high-poly GLB → rigged GLB+FBX (sync or async).
+  async autoRig(input: AutoRigInput): Promise<RigMotionResult> {
+    const payload: Record<string, unknown> = { model: HUNYUAN_GATEWAY_MODELS.autoRig, glb_url: input.glbUrl, n: 1 };
+    if (input.footnote) payload.footnote = input.footnote;
+
+    this.rateGuard.check();
+    const resp = await this.post(payload);
+    return this.collectModelResult(resp, 'auto_rigging');
+  }
+
+  // motion_retarget v1: rigged FBX + motion → animated GLB+FBX (sync or async).
+  async applyMotion(input: ApplyMotionInput): Promise<RigMotionResult> {
+    const payload: Record<string, unknown> = { model: HUNYUAN_GATEWAY_MODELS.motion, fbx_url: input.fbxUrl, motion_type: input.motionType, n: 1 };
+
+    this.rateGuard.check();
+    const resp = await this.post(payload);
+    return this.collectModelResult(resp, 'motion_retarget');
+  }
+
+  // low_poly (async via gateway): submit → poll until succeeded/failed.
+  async lowPoly(input: LowPolyInput): Promise<LowPolyResult> {
+    const payload: Record<string, unknown> = {
+      model: HUNYUAN_GATEWAY_MODELS.lowPoly,
+      glb_url: input.glbUrl,
+      polygon_type: input.polygonType ?? 'quadrilateral',
+      detail_level: input.detailLevel ?? 'high',
+      n: 1,
+    };
+    if (input.footnote) payload.footnote = input.footnote;
+
+    this.rateGuard.check();
+    const submit = await this.post(payload);
+    // Sync completion is rare but accepted; otherwise require a task id to poll.
+    if (normalizeGatewayStatus(submit.status) === 'succeeded' || extractGatewayUrls(submit).glb) {
+      const urls = extractGatewayUrls(submit);
+      const glbUrl = urls.glb;
+      if (!glbUrl) {
+        throw Object.assign(new Error('hunyuan low_poly returned no glb'), { code: 'provider_no_output' });
+      }
+      const taskId = (submit.id as string) ?? null;
+      const glb = await this.downloadImpl(glbUrl);
+      const previewImage = urls.__thumbnail ? await this.downloadImpl(urls.__thumbnail) : null;
+      return { sourceJobId: taskId, glb, previewImage };
+    }
+    const taskId = typeof submit.id === 'string' && submit.id ? submit.id : null;
+    if (!taskId) {
+      throw Object.assign(new Error('hunyuan low_poly submit returned no task id'), { code: 'provider_no_task' });
+    }
+    await audit(this.slug, { ts: new Date().toISOString(), provider: 'hunyuan_rest', mode: 'image', event: 'submit', sourceJobId: taskId, detail: 'low_poly' });
+
+    const urls = await this.pollLowPoly(taskId);
+    const glbUrl = urls.glb;
+    if (!glbUrl) {
+      throw Object.assign(new Error('hunyuan low_poly returned no glb'), { code: 'provider_no_output' });
+    }
+    const glb = await this.downloadImpl(glbUrl);
+    const previewImage = urls.__thumbnail ? await this.downloadImpl(urls.__thumbnail) : null;
+    return { sourceJobId: taskId, glb, previewImage };
+  }
+
+  // Poll the low_poly task via the gateway task endpoint.
+  private async pollLowPoly(taskId: string): Promise<Record<string, string>> {
+    try {
+      const resp = await this.gateway().pollTask(`${GATEWAY_POLL}/${taskId}`, {
+        timeoutMs: this.env.pollTimeoutMs,
+        intervalMs: this.env.pollIntervalMs,
+        label: 'hunyuan low_poly',
+      });
+      await audit(this.slug, { ts: new Date().toISOString(), provider: 'hunyuan_rest', mode: 'image', event: 'poll_succeeded', sourceJobId: taskId, detail: 'low_poly' });
+      return extractGatewayUrls(resp);
+    } catch (error) {
+      await audit(this.slug, { ts: new Date().toISOString(), provider: 'hunyuan_rest', mode: 'image', event: auditPollEvent(error), sourceJobId: taskId, detail: `low_poly:${error instanceof Error ? error.message : ''}` });
+      throw error;
+    }
+  }
+
+  // If the first response is still pending, poll; otherwise return as-is.
+  private async resolveSyncOrPoll(
+    resp: Record<string, unknown>,
+    label: string,
+  ): Promise<Record<string, unknown>> {
+    if (isGatewayFailed(resp)) return resp;
+    if (normalizeGatewayStatus(resp.status) === 'succeeded') return resp;
+    // Some sync responses omit status but already include data[] / *_url.
+    if (hasImmediateOutput(resp)) return resp;
+    const taskId = typeof resp.id === 'string' && resp.id ? resp.id : null;
+    if (!taskId) {
+      throw Object.assign(new Error(`hunyuan ${label} returned no task id and no output`), {
+        code: 'provider_no_task',
+      });
+    }
+    return this.gateway().pollTask(`${GATEWAY_POLL}/${taskId}`, {
+      timeoutMs: this.env.pollTimeoutMs,
+      intervalMs: this.env.pollIntervalMs,
+      label: `hunyuan ${label}`,
+    });
+  }
+
+  // Shared success/failure + download for sync/async endpoints (auto_rig, motion).
+  private async collectModelResult(
+    resp: Record<string, unknown>,
+    label: 'auto_rigging' | 'motion_retarget',
+  ): Promise<RigMotionResult> {
+    const resolved = await this.resolveSyncOrPoll(resp, label);
+    const sourceJobId = (resolved.id as string) ?? (resp.id as string) ?? null;
+    if (isGatewayFailed(resolved)) {
+      const msg = gatewayErrorMessage(resolved) ?? 'unknown';
+      await audit(this.slug, { ts: new Date().toISOString(), provider: 'hunyuan_rest', mode: 'image', event: 'rest_failed', sourceJobId, detail: `${label}:${msg}` });
+      throw Object.assign(new Error(`hunyuan ${label} failed: ${msg}`), { code: 'provider_failed' });
+    }
+
+    const urls = extractGatewayMeshUrls(resolved);
+    const files: ModelFileOut[] = [];
+    if (urls.glb_url) files.push({ format: 'glb', data: await this.downloadImpl(urls.glb_url) });
+    if (urls.fbx_url) files.push({ format: 'fbx', data: await this.downloadImpl(urls.fbx_url) });
+    if (files.length === 0) {
+      await audit(this.slug, { ts: new Date().toISOString(), provider: 'hunyuan_rest', mode: 'image', event: 'rest_no_output', sourceJobId, detail: label });
+      throw Object.assign(new Error(`hunyuan ${label} returned no model url`), { code: 'provider_no_output' });
+    }
+    await audit(this.slug, { ts: new Date().toISOString(), provider: 'hunyuan_rest', mode: 'image', event: 'rest_succeeded', sourceJobId, detail: label });
+    return { sourceJobId, files };
+  }
+
+  private async post(body: unknown): Promise<Record<string, unknown>> {
+    return this.gateway().post(GATEWAY_SUBMIT, body);
+  }
+
+  private async get(path: string): Promise<Record<string, unknown>> {
+    return this.gateway().get(path);
+  }
+
+  private gateway(): GatewayClient {
+    return new GatewayClient({ env: this.env, fetchImpl: this.fetchImpl, sleep: this.sleep });
+  }
+}
+
+function isGatewayFailed(resp: Record<string, unknown>): boolean {
+  if (normalizeGatewayStatus(resp.status) === 'failed') return true;
+  const err = resp.error as Record<string, unknown> | undefined;
+  return Boolean(err && (err.code || err.message));
+}
+
+function hasImmediateOutput(resp: Record<string, unknown>): boolean {
+  const mesh = extractGatewayMeshUrls(resp);
+  if (mesh.glb_url || mesh.fbx_url) return true;
+  const urls = extractGatewayUrls(resp);
+  return Boolean(urls.glb || urls.__thumbnail || extractSingleImageUrl(resp));
+}
+
+function auditPollEvent(error: unknown): 'poll_failed' | 'poll_timeout' {
+  return (error as { code?: unknown } | null)?.code === 'provider_timeout' ? 'poll_timeout' : 'poll_failed';
+}
+
+// Extract a single image URL from gateway data[] (for pose_std).
+function extractSingleImageUrl(resp: Record<string, unknown>): string | null {
+  const urls = extractGatewayUrls(resp);
+  if (urls.__thumbnail) return urls.__thumbnail;
+  const data = resp.data;
+  if (Array.isArray(data)) {
+    for (const item of data) {
+      if (!item || typeof item !== 'object') continue;
+      const obj = item as Record<string, unknown>;
+      if (typeof obj.url === 'string' && obj.url) return obj.url;
+    }
+  }
+  // Fallback: top-level *_url keys just in case the gateway embeds them.
+  for (const [key, value] of Object.entries(resp)) {
+    if (key.endsWith('_url') && typeof value === 'string' && value) return value;
+  }
+  return null;
+}
+
+// Extract glb_url + fbx_url from gateway data[] for rig/motion results.
+// Uses shared extractGatewayUrls (accepts type mesh | rigged_model | animated_model).
+function extractGatewayMeshUrls(resp: Record<string, unknown>): { glb_url?: string; fbx_url?: string } {
+  const urls = extractGatewayUrls(resp);
+  return { glb_url: urls.glb, fbx_url: urls.fbx };
+}
+
+function urlFormat(url: string): string | undefined {
+  const path = url.split('?', 1)[0] ?? url;
+  return path.split('.').pop()?.toLowerCase();
+}
+
+function isImageUrl(url: string): boolean {
+  return /\.(png|jpe?g|webp|gif)(?:\?|$)/i.test(url);
+}

package/server/providers/hunyuan-workflow.ts

@@ -0,0 +1,225 @@
+// HunyuanWorkflowProvider — real submit/poll client via the LiteLLM gateway.
+//
+// Decoupling (ADR-0001): talks to the remote gateway and returns a pure
+// ProviderResult with downloaded bytes. Auth uses a standard bearer header.
+// Submit goes to the unified `/v1/3d/generations` endpoint with a `model` field;
+// poll goes to `/v1/3d/tasks/{taskId}`. Status is lower-case.
+
+import type { ProviderResult, ProviderResultFile } from '../../shared/catalog';
+import type { FileFormat, FileRole, GenerationMode } from '../../shared/manifest';
+import type { HunyuanEnv } from '../env';
+import { audit } from '../audit';
+import { RateGuard } from '../rate-guard';
+import { extractGatewayUrls } from './gateway-data';
+import { GatewayClient, type FetchLike } from './gateway-client';
+import { HUNYUAN_GATEWAY_MODELS } from './gateway-models';
+
+const GATEWAY_SUBMIT = '/v1/3d/generations';
+const GATEWAY_POLL = '/v1/3d/tasks';
+
+const WF_MODEL: Record<HunyuanWorkflowMode, string> = {
+  text: HUNYUAN_GATEWAY_MODELS.text,
+  image: HUNYUAN_GATEWAY_MODELS.image,
+  views: HUNYUAN_GATEWAY_MODELS.views,
+};
+
+export type HunyuanWorkflowMode = 'text' | 'image' | 'views';
+
+export type ViewSlot =
+  | 'front_image_url'
+  | 'back_image_url'
+  | 'left_image_url'
+  | 'right_image_url'
+  | 'top_image_url'
+  | 'bottom_image_url'
+  | 'front_left_image_url'
+  | 'front_right_image_url';
+
+export interface HunyuanGenerateInput {
+  mode: HunyuanWorkflowMode;
+  prompt?: string;
+  imageUrl?: string;
+  views?: Partial<Record<ViewSlot, string>>;
+  enablePbr?: boolean;
+  enableFbxUrl?: boolean;
+  faceCount?: number;
+}
+
+export type DownloadLike = (url: string) => Promise<Uint8Array>;
+
+export interface HunyuanProviderDeps {
+  env: HunyuanEnv;
+  slug: string;
+  fetchImpl?: FetchLike;
+  downloadImpl?: DownloadLike;
+  rateGuard?: RateGuard;
+  sleep?: (ms: number) => Promise<void>;
+}
+
+// Map a gateway data[] entry format to a durable manifest file role+format.
+const DATA_TYPE_TO_FILE: Record<string, { role: FileRole; format: FileFormat }> = {
+  glb: { role: 'source_mesh', format: 'glb' },
+  fbx: { role: 'source_mesh', format: 'fbx' },
+  obj: { role: 'source_mesh', format: 'obj' },
+};
+
+export class HunyuanWorkflowProvider {
+  private readonly env: HunyuanEnv;
+  private readonly slug: string;
+  private readonly fetchImpl: FetchLike;
+  private readonly downloadImpl: DownloadLike;
+  private readonly rateGuard: RateGuard;
+  private readonly sleep: (ms: number) => Promise<void>;
+
+  constructor(deps: HunyuanProviderDeps) {
+    this.env = deps.env;
+    this.slug = deps.slug;
+    this.fetchImpl = deps.fetchImpl ?? ((url, init) => fetch(url, init));
+    this.downloadImpl =
+      deps.downloadImpl ??
+      (async (url) => this.gateway().download(url, { format: urlFormat(url), image: isImageUrl(url) }));
+    this.rateGuard = deps.rateGuard ?? new RateGuard(this.env.rateLimitPerMin);
+    this.sleep = deps.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
+  }
+
+  async generate(input: HunyuanGenerateInput): Promise<ProviderResult> {
+    const mode = input.mode;
+    if (mode === 'views') validateHunyuanViews(input.views);
+    const model = WF_MODEL[mode];
+    const payload = buildHunyuanWorkflowPayload(model, input);
+
+    this.rateGuard.check();
+
+    const submitResp = await this.post(payload);
+    const sourceJobId = submitTaskId(submitResp);
+    if (!sourceJobId) {
+      throw Object.assign(new Error('hunyuan workflow submit returned no task id'), { code: 'provider_no_task' });
+    }
+    await audit(this.slug, { ts: new Date().toISOString(), provider: 'hunyuan_workflow', mode, event: 'submit', sourceJobId });
+
+    const urls = await this.poll(sourceJobId, mode);
+    const files: ProviderResultFile[] = [];
+    const seenRoles = new Set<string>();
+    for (const [key, mapping] of Object.entries(DATA_TYPE_TO_FILE)) {
+      const url = urls[key];
+      if (!url) continue;
+      const roleKey = `${mapping.role}:${mapping.format}`;
+      if (seenRoles.has(roleKey)) continue;
+      seenRoles.add(roleKey);
+      const data = await this.downloadImpl(url);
+      files.push({ role: mapping.role, format: mapping.format, data });
+    }
+    if (urls.__thumbnail) {
+      files.push({ role: 'preview_image', format: 'png', data: await this.downloadImpl(urls.__thumbnail) });
+    }
+    if (!files.some((f) => f.role === 'source_mesh' && f.format === 'glb')) {
+      throw Object.assign(new Error('hunyuan workflow succeeded without a GLB mesh'), {
+        code: 'provider_no_output',
+      });
+    }
+
+    return {
+      provider: 'hunyuan_workflow',
+      mode: mode as GenerationMode,
+      providerMode: 'real',
+      sourceJobId,
+      prompt: input.prompt ?? null,
+      files,
+    };
+  }
+
+  private async poll(
+    taskId: string,
+    mode: HunyuanWorkflowMode,
+  ): Promise<Record<string, string>> {
+    try {
+      const resp = await this.gateway().pollTask(`${GATEWAY_POLL}/${taskId}`, {
+        timeoutMs: this.env.pollTimeoutMs,
+        intervalMs: this.env.pollIntervalMs,
+        label: 'hunyuan workflow',
+      });
+      await audit(this.slug, { ts: new Date().toISOString(), provider: 'hunyuan_workflow', mode, event: 'poll_succeeded', sourceJobId: taskId, detail: 'succeeded' });
+      return extractGatewayUrls(resp);
+    } catch (error) {
+      await audit(this.slug, { ts: new Date().toISOString(), provider: 'hunyuan_workflow', mode, event: auditPollEvent(error), sourceJobId: taskId, detail: error instanceof Error ? error.message : undefined });
+      throw error;
+    }
+  }
+
+  private async post(body: unknown): Promise<Record<string, unknown>> {
+    return this.gateway().post(GATEWAY_SUBMIT, body);
+  }
+
+  private async get(path: string): Promise<Record<string, unknown>> {
+    return this.gateway().get(path);
+  }
+
+  private gateway(): GatewayClient {
+    return new GatewayClient({ env: this.env, fetchImpl: this.fetchImpl, sleep: this.sleep });
+  }
+}
+
+function submitTaskId(resp: Record<string, unknown>): string | null {
+  return (resp.id as string) ?? null;
+}
+
+function auditPollEvent(error: unknown): 'poll_failed' | 'poll_timeout' {
+  return (error as { code?: unknown } | null)?.code === 'provider_timeout' ? 'poll_timeout' : 'poll_failed';
+}
+
+function urlFormat(url: string): string | undefined {
+  const path = url.split('?', 1)[0] ?? url;
+  return path.split('.').pop()?.toLowerCase();
+}
+
+function isImageUrl(url: string): boolean {
+  return /\.(png|jpe?g|webp|gif)(?:\?|$)/i.test(url);
+}
+
+const VIEW_SLOTS: ViewSlot[] = [
+  'front_image_url',
+  'back_image_url',
+  'left_image_url',
+  'right_image_url',
+  'top_image_url',
+  'bottom_image_url',
+  'front_left_image_url',
+  'front_right_image_url',
+];
+
+/** Require front + at least one extra non-empty view before submit. */
+export function validateHunyuanViews(views: Partial<Record<ViewSlot, string>> | undefined): void {
+  const filled = VIEW_SLOTS.filter((slot) => Boolean(views?.[slot]?.trim()));
+  if (!views?.front_image_url?.trim()) {
+    throw Object.assign(new Error('hunyuan views require front_image_url'), { code: 'invalid_views' });
+  }
+  if (filled.length < 2) {
+    throw Object.assign(new Error('hunyuan views require front_image_url plus at least one additional view'), {
+      code: 'invalid_views',
+    });
+  }
+}
+
+/** Pure payload builder — only non-empty view slots are included. */
+export function buildHunyuanWorkflowPayload(
+  model: string,
+  input: HunyuanGenerateInput,
+): Record<string, unknown> {
+  const payload: Record<string, unknown> = { model };
+  if (input.faceCount && input.faceCount > 0) payload.face_count = input.faceCount;
+  if (typeof input.enablePbr === 'boolean') payload.enable_pbr = input.enablePbr;
+  if (typeof input.enableFbxUrl === 'boolean') payload.enable_fbx_url = input.enableFbxUrl;
+
+  if (input.mode === 'text') {
+    payload.prompt = input.prompt ?? '';
+  } else if (input.mode === 'image') {
+    payload.image_url = input.imageUrl ?? '';
+  } else {
+    const views = input.views ?? {};
+    for (const slot of VIEW_SLOTS) {
+      const url = views[slot]?.trim();
+      if (url) payload[slot] = url;
+    }
+  }
+  return payload;
+}