Cloud Functions API

All Cloud Functions are deployed at us-central1 in Firebase project yugmastudio-addcd. Callable functions require Firebase Authentication.

Invocation

import { getFunctions, httpsCallable } from 'firebase/functions'

const functions = getFunctions()
const fn = httpsCallable(functions, 'functionName')
const result = await fn({ ...params })

---

AI Functions

aiCompose

The AI brain. Runs a multi-stage composition pipeline: optional planning pass, then an agentic tool-use loop (up to 8 iterations).

Timeout: 120s | Secrets: Provider config from Firestore

Field	Type	Required	Description
messages	{role, content}[]	Yes	Conversation history
sceneContext	object	No	YSL scene text, objects, environment, styleHint
mode	'creative' | 'precise'	No	Temperature toggle (0.7 / 0.2)
sessionId	string	No	Session ID for cross-session persistence

Returns:

{
  "text": "I've created a sci-fi hangar with...",
  "toolCalls": [{ "name": "add_object", "input": {...} }, ...],
  "iterations": 3,
  "plan": "1. Create floor...\n2. Add walls..."
}

getRecentAISessions

Fetch recent AI sessions for session hydration on mount.

Field	Type	Required	Description
limit	number	No	Max sessions (default 5, max 25)
loadLatestMessages	boolean	No	Include full message list of most recent session

Returns:

{
  "sessions": [{ "session_id": "...", "title": "...", "message_count": 5, "updated_at": "..." }],
  "latest": { "sessionId": "...", "messages": [...] }
}

generateMaterial

Generate PBR material values from a text description.

Field	Type	Required	Description
description	string	Yes	e.g. "weathered copper with patina"

Returns: { color, roughness, metalness, emissive, emissiveIntensity }

inspectMaterial

Analyze a material and suggest improvements.

Field	Type	Required	Description
material	object	Yes	Current material properties

Returns: { analysis, suggestions[] }

---

Generation Functions

generateAsset

Start a Meshy.ai text-to-3D generation job.

Field	Type	Required	Description
prompt	string	Yes	Description of the 3D model

Returns: { jobId, status: 'pending' }

checkGenerationStatus

Poll a Meshy generation job for completion.

Field	Type	Required	Description
jobId	string	Yes	Meshy job ID

Returns: { status, progress, glbUrl? }

---

Project Functions

deleteProject

Delete a project and cascade-remove associated assets.

Field	Type	Required	Description
projectId	string	Yes	Project to delete

Authorization: Owner only.

exportScene

Convert a Yugma scene to glTF 2.0 JSON.

Field	Type	Required	Description
scene	object	Yes	Scene JSON

---

Storage Functions

generateSignedUploadUrl

Field	Type	Required
filename	string	Yes

Returns: { url, path } — PUT to the URL with appropriate Content-Type.

generateSignedDownloadUrl

Field	Type	Required
path	string	Yes

Returns: { url } — expires after 1 hour.

---

Phase Stub Functions

These functions are scaffolded but their backends are not yet connected:

startVideoReconstruction (Phase 12)

Creates a videoJobs doc. Returns { jobId }. TODO: dispatch to Cloud Run ML orchestrator.

renderStoryboard (Phase 16)

Creates a renderJobs doc after verifying storyboard ownership. Returns { jobId }. TODO: headless R3F + ffmpeg worker.

octopartProxy (Phase 14)

Returns mock component data (ESP32, BME280, SSD1306). TODO: wire to Nexar GraphQL API with NEXAR_API_KEY.

---

Auth Triggers

onUserCreate (v1)

Seeds a user profile document in Firestore on signup.

onUserDelete (v1)

Cascade-deletes user profile and projects on account deletion.

---

Error Codes

Code	Meaning
unauthenticated	No valid auth token
invalid-argument	Missing or invalid parameters
not-found	Resource doesn't exist
permission-denied	User lacks access
resource-exhausted	Rate limit exceeded (30/hr for AI)

---

Secrets

Secret	Used by	Status
ANTHROPIC_API_KEY	aiCompose, generateMaterial, inspectMaterial	Set via admin panel
MESHY_API_KEY	generateAsset, checkGenerationStatus	Set in firebase secrets
NEXAR_API_KEY	octopartProxy	Not yet set