@forgeax-extension/character-3d 0.1.2

package/server/providers/rodin-gateway.ts

@@ -0,0 +1,193 @@
+// Rodin via LiteLLM GatewayClient (`rodin-3d`). Do not import rodin.ts
+// (Hyper3D multipart) and do not read RODIN_API_KEY.
+//
+// C1 2026-08-14: text requires `prompt`; image requires `image_url(s)`.
+// Multi-view is the same image model with 2–5 URLs (official 1–5).
+
+import type { ProviderResult, ProviderResultFile } from '../../shared/catalog';
+import type { FileFormat, FileRole, GenerationMode } from '../../shared/manifest';
+import type { RodinEnv } from '../env';
+import { audit } from '../audit';
+import { RateGuard } from '../rate-guard';
+import {
+  explainRodinGatewayError,
+  fitsRodinAspect,
+  readImageSize,
+  rodinAspectRejectMessage,
+} from '../../shared/rodin-image';
+import { extractGatewayUrls } from './gateway-data';
+import { GatewayClient, type FetchLike } from './gateway-client';
+import { RODIN_GATEWAY_MODELS } from './gateway-models';
+
+const GATEWAY_SUBMIT = '/v1/3d/generations';
+const GATEWAY_POLL = '/v1/3d/tasks';
+
+export type RodinGatewayMode = 'text' | 'image';
+
+export interface RodinGatewayGenerateInput {
+  mode: RodinGatewayMode | 'views';
+  prompt?: string;
+  imageUrl?: string;
+  imageUrls?: string[];
+}
+
+export type DownloadLike = (url: string) => Promise<Uint8Array>;
+
+export interface RodinGatewayDeps {
+  env: RodinEnv;
+  slug: string;
+  fetchImpl?: FetchLike;
+  downloadImpl?: DownloadLike;
+  rateGuard?: RateGuard;
+  sleep?: (ms: number) => Promise<void>;
+}
+
+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 function buildRodinGatewayPayload(input: RodinGatewayGenerateInput): Record<string, unknown> {
+  const payload: Record<string, unknown> = { model: RODIN_GATEWAY_MODELS.generate };
+  if (input.mode === 'text') {
+    payload.prompt = input.prompt ?? '';
+  } else {
+    const urls = (input.imageUrls ?? []).map((u) => u.trim()).filter(Boolean).slice(0, 5);
+    if (urls.length > 1) payload.image_urls = urls;
+    else payload.image_url = input.imageUrl?.trim() || urls[0] || '';
+    const flagged = input.prompt?.trim();
+    if (flagged) payload.prompt = flagged;
+  }
+  return payload;
+}
+
+export function rodinImageUrls(input: RodinGatewayGenerateInput): string[] {
+  const listed = (input.imageUrls ?? []).map((u) => u.trim()).filter(Boolean).slice(0, 5);
+  if (listed.length > 0) return listed;
+  const one = input.imageUrl?.trim();
+  return one ? [one] : [];
+}
+
+export async function assertRodinImageUrls(urls: string[], fetchImpl: FetchLike): Promise<void> {
+  await Promise.all(
+    urls.map(async (url) => {
+      const resp = await fetchImpl(url, { method: 'GET' });
+      if (!resp.ok) return;
+      const bytes = new Uint8Array(await resp.arrayBuffer());
+      const size = readImageSize(bytes);
+      if (!size) return;
+      if (!fitsRodinAspect(size.width, size.height)) {
+        throw Object.assign(new Error(rodinAspectRejectMessage(size.width, size.height)), {
+          code: 'rodin_image_aspect',
+        });
+      }
+    }),
+  );
+}
+
+function rewriteRodinError(error: unknown): never {
+  if (error && typeof error === 'object' && (error as { code?: string }).code === 'rodin_image_aspect') {
+    throw error;
+  }
+  const message = error instanceof Error ? error.message : String(error);
+  const explained = explainRodinGatewayError(message);
+  if (explained) {
+    throw Object.assign(new Error(explained), {
+      code: 'rodin_image_aspect',
+      cause: error,
+    });
+  }
+  throw error;
+}
+
+export class RodinGatewayProvider {
+  private readonly env: RodinEnv;
+  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: RodinGatewayDeps) {
+    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: RodinGatewayGenerateInput): Promise<ProviderResult> {
+    const payload = buildRodinGatewayPayload(input);
+    this.rateGuard.check();
+    try {
+      if (input.mode !== 'text') {
+        await assertRodinImageUrls(rodinImageUrls(input), this.fetchImpl);
+      }
+    } catch (error) {
+      rewriteRodinError(error);
+    }
+    let submitResp: Record<string, unknown>;
+    try {
+      submitResp = await this.gateway().post(GATEWAY_SUBMIT, payload);
+    } catch (error) {
+      rewriteRodinError(error);
+    }
+    const sourceJobId = typeof submitResp.id === 'string' ? submitResp.id : null;
+    if (!sourceJobId) {
+      throw Object.assign(new Error('rodin gateway submit returned no task id'), { code: 'provider_no_task' });
+    }
+    await audit(this.slug, {
+      ts: new Date().toISOString(),
+      provider: 'rodin',
+      mode: input.mode === 'views' ? 'image' : input.mode,
+      event: 'submit',
+      sourceJobId,
+    });
+
+    const resp = await this.gateway().pollTask(`${GATEWAY_POLL}/${sourceJobId}`, {
+      timeoutMs: this.env.pollTimeoutMs,
+      intervalMs: this.env.pollIntervalMs,
+      label: 'rodin gateway',
+    });
+    const urls = extractGatewayUrls(resp);
+    const files: ProviderResultFile[] = [];
+    for (const [key, mapping] of Object.entries(DATA_TYPE_TO_FILE)) {
+      const url = urls[key];
+      if (!url) continue;
+      files.push({ role: mapping.role, format: mapping.format, data: await this.downloadImpl(url) });
+    }
+    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('rodin gateway succeeded without a GLB mesh'), {
+        code: 'provider_no_output',
+      });
+    }
+    return {
+      provider: 'rodin',
+      mode: input.mode as GenerationMode,
+      providerMode: 'real',
+      sourceJobId,
+      prompt: input.prompt ?? null,
+      files,
+    };
+  }
+
+  private gateway(): GatewayClient {
+    return new GatewayClient({ env: this.env, fetchImpl: this.fetchImpl, sleep: this.sleep });
+  }
+}
+
+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/rodin.ts

@@ -0,0 +1,253 @@
+// RodinProvider — real submit/poll/download client for the Hyper3D Rodin API.
+//
+// Decoupling (ADR-0001): like the other providers, this talks to the remote API
+// and returns a pure ProviderResult with downloaded bytes. It knows nothing
+// about cache, asset-store, or manifests. Auth uses a standard bearer header.
+//
+// Contract (developer.hyper3d.ai, verified 2026-06-11):
+//   - submit:   POST {base}/api/v2/rodin   multipart/form-data
+//               → { uuid, jobs: { subscription_key } }
+//   - status:   POST {base}/api/v2/status  { subscription_key }
+//               → { jobs: [{ status: Waiting|Generating|Done|Failed }] }
+//   - download: POST {base}/api/v2/download { task_uuid }
+//               → { list: [{ url, name }] }
+//
+// Real-API end-to-end VERIFIED 2026-06-11 (text-to-3D, key + Business sub):
+// submit/poll(6 sub-jobs all Done)/download returned `base_basic_pbr.glb` +
+// `preview.webp`, persisted real per-game with providerMode='real'. Note the
+// preview is a .webp (kept as preview_image; FileFormat carries 'webp').
+//
+// Mode selection is implicit: images present → image/views (Image-to-3D),
+// none → text (Text-to-3D). We pin tier=Regular, material=PBR,
+// geometry_file_format=glb, and pass quality_override for poly count. Multi-view
+// uses condition_mode=concat with several image files.
+//
+// Image inputs arrive as URLs (the upload/pose flow hosts local files first).
+// Rodin needs bytes, so the provider downloads each URL before attaching it as
+// a multipart file — this also sidesteps any provider-side URL fetch.
+
+import type { ProviderResult, ProviderResultFile } from '../../shared/catalog';
+import type { FileFormat, FileRole, GenerationMode } from '../../shared/manifest';
+import type { RodinEnv } from '../env';
+import { audit } from '../audit';
+import { RateGuard } from '../rate-guard';
+
+const PATH_SUBMIT = '/api/v2/rodin';
+const PATH_STATUS = '/api/v2/status';
+const PATH_DOWNLOAD = '/api/v2/download';
+
+const DONE = 'Done';
+const FAILED = 'Failed';
+
+export type RodinMode = 'text' | 'image' | 'views';
+
+export interface RodinGenerateInput {
+  mode: RodinMode;
+  prompt?: string;
+  imageUrl?: string;
+  imageUrls?: string[];
+  // Customize poly count (Rodin quality_override; ranges ~2000–200000).
+  qualityOverride?: number;
+  params?: Record<string, string | number | boolean>;
+}
+
+export type FetchLike = (url: string, init: RequestInit) => Promise<Response>;
+export type DownloadLike = (url: string) => Promise<Uint8Array>;
+
+export interface RodinProviderDeps {
+  env: RodinEnv;
+  // Active game slug for the per-game audit trail (ADR-0002). Smokes may pass any.
+  slug: string;
+  fetchImpl?: FetchLike;
+  downloadImpl?: DownloadLike;
+  rateGuard?: RateGuard;
+  sleep?: (ms: number) => Promise<void>;
+}
+
+// Map a downloaded result file's name to a durable role+format. The Rodin
+// download list mixes the geometry file, textures, and a preview webp.
+function classifyFile(name: string): { role: FileRole; format: FileFormat } | null {
+  const lower = name.toLowerCase();
+  if (lower.endsWith('.glb')) return { role: 'source_mesh', format: 'glb' };
+  if (lower.endsWith('.fbx')) return { role: 'source_mesh', format: 'fbx' };
+  if (lower.endsWith('.obj')) return { role: 'source_mesh', format: 'obj' };
+  if (lower.endsWith('.usdz')) return { role: 'source_mesh', format: 'usdz' };
+  if (lower.endsWith('.stl')) return { role: 'source_mesh', format: 'stl' };
+  if (lower.endsWith('.png')) return { role: 'preview_image', format: 'png' };
+  if (lower.endsWith('.jpg') || lower.endsWith('.jpeg')) return { role: 'preview_image', format: 'jpg' };
+  if (lower.endsWith('.webp')) return { role: 'preview_image', format: 'webp' };
+  // Texture maps and any other variants are not part of our durable contract.
+  return null;
+}
+
+export class RodinProvider {
+  private readonly env: RodinEnv;
+  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: RodinProviderDeps) {
+    this.env = deps.env;
+    this.slug = deps.slug;
+    this.fetchImpl = deps.fetchImpl ?? ((url, init) => fetch(url, init));
+    this.downloadImpl =
+      deps.downloadImpl ?? (async (url) => new Uint8Array(await (await fetch(url)).arrayBuffer()));
+    this.rateGuard = deps.rateGuard ?? new RateGuard(this.env.rateLimitPerMin);
+    this.sleep = deps.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
+  }
+
+  async generate(input: RodinGenerateInput): Promise<ProviderResult> {
+    const form = await this.buildForm(input);
+
+    // Guard BEFORE the quotaed submit.
+    this.rateGuard.check();
+
+    const submit = await this.postForm(PATH_SUBMIT, form);
+    const uuid = submit.uuid as string | undefined;
+    const jobs = submit.jobs as { subscription_key?: string } | undefined;
+    const subscriptionKey = jobs?.subscription_key;
+    if (!uuid || !subscriptionKey) {
+      throw Object.assign(new Error('rodin submit returned no task uuid/subscription_key'), {
+        code: 'provider_no_task',
+      });
+    }
+    await audit(this.slug, {
+      ts: new Date().toISOString(),
+      provider: 'rodin',
+      mode: input.mode,
+      event: 'submit',
+      sourceJobId: uuid,
+    });
+
+    await this.poll(input.mode, uuid, subscriptionKey);
+
+    const list = await this.download(uuid);
+    const files: ProviderResultFile[] = [];
+    let haveMesh = false;
+    let havePreview = false;
+    for (const item of list) {
+      const cls = classifyFile(item.name);
+      if (!cls) continue;
+      // Keep one mesh + one preview; ignore extra texture/format variants.
+      if (cls.role === 'source_mesh') {
+        if (haveMesh || cls.format !== 'glb') continue;
+        haveMesh = true;
+      } else if (cls.role === 'preview_image') {
+        if (havePreview) continue;
+        havePreview = true;
+      }
+      files.push({ role: cls.role, format: cls.format, data: await this.downloadImpl(item.url) });
+    }
+    if (!haveMesh) {
+      throw Object.assign(new Error('rodin download returned no GLB mesh'), {
+        code: 'provider_no_output',
+      });
+    }
+
+    return {
+      provider: 'rodin',
+      mode: input.mode as GenerationMode,
+      providerMode: 'real',
+      sourceJobId: uuid,
+      prompt: input.prompt ?? null,
+      files,
+    };
+  }
+
+  private async buildForm(input: RodinGenerateInput): Promise<FormData> {
+    const form = new FormData();
+    form.append('tier', 'Regular');
+    form.append('material', 'PBR');
+    form.append('geometry_file_format', 'glb');
+    if (input.qualityOverride !== undefined) {
+      form.append('quality_override', String(Math.round(input.qualityOverride)));
+    }
+    if (input.prompt && input.prompt.trim()) form.append('prompt', input.prompt.trim());
+
+    const urls =
+      input.mode === 'image'
+        ? input.imageUrl
+          ? [input.imageUrl]
+          : []
+        : input.mode === 'views'
+          ? input.imageUrls ?? []
+          : [];
+    if (urls.length > 1) form.append('condition_mode', 'concat');
+    let i = 0;
+    for (const url of urls) {
+      const bytes = await this.downloadImpl(url);
+      // Bun/Hono FormData accepts a Blob with a filename for multipart files.
+      const blob = new Blob([bytes as BlobPart]);
+      form.append('images', blob, `input-${i}.png`);
+      i += 1;
+    }
+    if (input.mode === 'text' && (!input.prompt || !input.prompt.trim())) {
+      throw Object.assign(new Error('rodin text mode requires a prompt'), { code: 'invalid_prompt' });
+    }
+    if (input.mode !== 'text' && urls.length === 0) {
+      throw Object.assign(new Error('rodin image/views mode requires at least one image'), {
+        code: 'invalid_image_url',
+      });
+    }
+    if (input.params) {
+      for (const [key, value] of Object.entries(input.params)) {
+        form.set(key, String(value));
+      }
+    }
+    return form;
+  }
+
+  private async poll(mode: RodinMode, uuid: string, subscriptionKey: string): Promise<void> {
+    const deadline = Date.now() + this.env.pollTimeoutMs;
+    while (Date.now() < deadline) {
+      const resp = await this.postJson(PATH_STATUS, { subscription_key: subscriptionKey });
+      const jobs = Array.isArray(resp.jobs) ? (resp.jobs as Array<{ status?: string }>) : [];
+      const statuses = jobs.map((j) => String(j.status ?? ''));
+      if (statuses.length > 0 && statuses.every((s) => s === DONE || s === FAILED)) {
+        if (statuses.some((s) => s === FAILED)) {
+          await audit(this.slug, { ts: new Date().toISOString(), provider: 'rodin', mode, event: 'poll_failed', sourceJobId: uuid, detail: 'Failed' });
+          throw Object.assign(new Error('rodin task failed'), { code: 'provider_failed' });
+        }
+        await audit(this.slug, { ts: new Date().toISOString(), provider: 'rodin', mode, event: 'poll_succeeded', sourceJobId: uuid, detail: DONE });
+        return;
+      }
+      await this.sleep(this.env.pollIntervalMs);
+    }
+    await audit(this.slug, { ts: new Date().toISOString(), provider: 'rodin', mode, event: 'poll_timeout', sourceJobId: uuid });
+    throw Object.assign(new Error('rodin poll timed out'), { code: 'provider_timeout' });
+  }
+
+  private async download(uuid: string): Promise<Array<{ url: string; name: string }>> {
+    const resp = await this.postJson(PATH_DOWNLOAD, { task_uuid: uuid });
+    const list = Array.isArray(resp.list) ? (resp.list as Array<Record<string, unknown>>) : [];
+    return list
+      .map((e) => ({ url: String(e.url ?? ''), name: String(e.name ?? '') }))
+      .filter((e) => e.url && e.name);
+  }
+
+  private async postForm(path: string, form: FormData): Promise<Record<string, unknown>> {
+    const resp = await this.fetchImpl(`${this.env.baseUrl}${path}`, {
+      method: 'POST',
+      headers: { Authorization: `Bearer ${this.env.apiKey}` },
+      body: form,
+    });
+    if (!resp.ok) {
+      throw Object.assign(new Error(`rodin http ${resp.status}`), { code: 'provider_http_error' });
+    }
+    return (await resp.json()) as Record<string, unknown>;
+  }
+
+  private async postJson(path: string, body: unknown): Promise<Record<string, unknown>> {
+    const resp = await this.fetchImpl(`${this.env.baseUrl}${path}`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json', Authorization: `Bearer ${this.env.apiKey}` },
+      body: JSON.stringify(body),
+    });
+    if (!resp.ok) {
+      throw Object.assign(new Error(`rodin http ${resp.status}`), { code: 'provider_http_error' });
+    }
+    return (await resp.json()) as Record<string, unknown>;
+  }
+}