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. Delegates to composeCore and runs an agentic tool-use loop (default 3 iterations, configurable 0–5 via AI_MAX_ITERATIONS). After each iteration a pure-math scene audit appends a SCENE AUDIT: line to the tool results (heavy overlaps, floating/sunken/oversized objects) so the model self-corrects on its next turn. aiComposeStream is the SSE variant — same composeCore, timeoutSeconds: 300.

Timeout: 180s | Secrets: GEMINI_API_KEY

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,
  "totalToolCalls": 7
}

generateMaterial

Generate PBR material values from a text description. Requires a paid tier and shares a bounded hourly material-AI bucket with inspectMaterial.

Field	Type	Required	Description
prompt	string (1–500 chars)	Yes	e.g. "weathered copper with patina"

Returns: { color, roughness, metalness, emissiveColor?, emissiveIntensity? }

inspectMaterial

Analyze a material and suggest improvements. Requires a paid tier; serialized input is bounded to 2,000 characters.

Field	Type	Required	Description
material	object	Yes	Current material properties

Returns: { description, suggestions[] }

---

Project and Storage Operations

Project export and version history run in the client. Asset transfers use the Firebase Storage SDK directly and are authorized by storage.rules; Yugma does not expose server-signed upload or download callables.

---

Billing

stripeWebhook

HTTP endpoint (not a callable). Stripe posts subscription events here. It verifies the Stripe-Signature header using Stripe's v1 scheme (HMAC-SHA256 over <timestamp>.<rawBody>, constant-time compare, 5-minute tolerance, keyed by STRIPE_WEBHOOK_SECRET) and handles three events: checkout.session.completed, customer.subscription.updated, and customer.subscription.deleted.

Processing is level-triggered, not edge-triggered: every subscription is mirrored into users/{uid}.billingSubs, and on each event the effective tier (premium / ultimate) is recomputed as the highest tier among still-active subscriptions — so out-of-order or duplicate deliveries converge to the customer's true entitlement. Idempotency is enforced via stripeEvents/{event.id}; test-mode (livemode !== true) events never grant a tier. The buyer's UID arrives as client_reference_id on the Payment Link checkout, and the tier is read from metadata.tier on the session / price.

The former Phase 12/14/16 stub functions (startVideoReconstruction, octopartProxy, renderStoryboard) were removed from the codebase in the 2026-07 cleanup and are not deployed. The Meshy text-to-3D functions (generateAsset, sweepGenerationJobs) and the dormant lemonsqueezyWebhook were removed in the 2026-08 provider consolidation — Gemini is the only AI provider and Stripe the only billing path.

---

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
GEMINI_API_KEY	aiCompose, aiComposeStream, aiSceneAudit, generateMaterial, inspectMaterial, mcpServer	Set via firebase secrets
STRIPE_WEBHOOK_SECRET	stripeWebhook	Set via firebase secrets